接口安全规范

本文档描述了商户平台对接接口的安全规范，包括认证流程、请求签名、数据加密等内容。

# 1. 认证流程

POST /oauth/token

商户在调用接口前，需要先获取访问凭证（access_token）。认证流程如下：

  1. 商户向平台申请获取AppID和AppSecret
  2. 商户使用AppID和AppSecret调用认证接口获取access_token
  3. 商户在后续接口请求中使用access_token进行身份验证

请求参数

参数名 类型 必填 描述
app_id String 是 应用ID
app_secret String 是 应用密钥
grant_type String 是 授权类型，固定值：client_credentials

响应参数

字段名 类型 描述
access_token String 访问凭证
token_type String 凭证类型，固定值：Bearer
expires_in Integer 凭证有效期，单位：秒

请求示例

{
  "app_id": "merchant123456",
  "app_secret": "a1b2c3d4e5f6g7h8i9j0",
  "grant_type": "client_credentials"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 7200
  },
  "timestamp": 1623123456789
}

# 2. 请求签名

为确保接口调用的安全性，除了使用access_token外，还需要对请求进行签名。签名流程如下：

  1. 将请求参数按照参数名ASCII码从小到大排序
  2. 将排序后的参数按照参数名=参数值的格式拼接成字符串，参数之间用&连接
  3. 在拼接好的字符串末尾加上&app_secret=应用密钥
  4. 对拼接好的字符串进行MD5加密，得到32位小写签名字符串
  5. 将签名字符串作为sign参数添加到请求中

签名示例

原始请求参数：

{
  "app_id": "merchant123456",
  "timestamp": 1623123456789,
  "nonce": "abcdef123456",
  "sku_code": "SP123456",
  "quantity": 100
}

参数排序并拼接：

app_id=merchant123456&nonce=abcdef123456&quantity=100&sku_code=SP123456×tamp=1623123456789&app_secret=a1b2c3d4e5f6g7h8i9j0

MD5加密后：

7d5a8d5b1f5c9a8b7c6d5e4f3a2b1c0d

最终请求参数：

{
  "app_id": "merchant123456",
  "timestamp": 1623123456789,
  "nonce": "abcdef123456",
  "sku_code": "SP123456",
  "quantity": 100,
  "sign": "7d5a8d5b1f5c9a8b7c6d5e4f3a2b1c0d"
}

# 3. 请求限流

为了保障平台的稳定性和安全性，对接口的调用频率进行了限制。

限流规则

接口类型 限流规则 说明
普通接口 100次/分钟 单个商户ID每分钟可调用100次
批量接口 20次/分钟 单个商户ID每分钟可调用20次
查询接口 200次/分钟 单个商户ID每分钟可调用200次

超出限流处理

当请求超出限流阈值时，接口将返回如下错误：

{
  "code": 429,
  "message": "请求过于频繁，请稍后再试",
  "data": null,
  "timestamp": 1623123456789
}

# 4. 数据加密

# 5. IP白名单

为进一步增强安全性，平台支持配置IP白名单：

  1. 商户可以在平台管理后台设置调用接口的IP白名单
  2. 来自非白名单IP的请求将被拒绝
  3. 建议配置固定的服务器IP，避免使用动态IP

# 6. 回调安全

平台向商户系统发送回调通知时，采用以下安全措施：

  1. 在HTTP Header中添加签名信息
    • X-Callback-Timestamp：回调时间戳
    • X-Callback-Signature：回调签名
  2. 签名算法：HMAC-SHA256(secret_key, body + timestamp)
  3. 商户系统需要验证签名，以确保回调请求来自平台
  4. 建议商户系统在处理回调请求时进行幂等性处理，避免重复处理

# 7. 异常处理

在接口通信过程中可能出现各种异常情况，建议按照以下方式处理：

  1. 网络异常：实施请求重试机制，推荐按照指数退避策略进行重试
  2. 验签失败：检查签名算法和参数，确保和平台保持一致
  3. 授权失败：检查access_token是否过期，及时刷新令牌
  4. 业务异常：根据返回的错误码和错误信息进行针对性处理