三、通用约定

3.1 获取ID和密钥

供应商登录东篱商城的供应商后台（sup.keyan.net.cn），按下图（箭头指向1、2步骤）申请对接，申请后，等待东篱运营人员审核后，获取appid、密钥。

3.2 基础地址

{host}/openapi

实际 {host} 由不同部署环境提供。
测试环境：https://www.do.keyan.net.cn
生产环境：https://www.keyan.net.cn

3.3 请求格式

Content-Type: application/json

字符编码统一为 UTF-8，时间统一使用 Unix 毫秒时间戳。

3.4 身份认证

请求必须携带以下 Header：

供应商身份由 X-Openapi-App-Id 对应的开放平台客户端确定，请求体中不传 supplierId。

3.4.1 签名算法

平台分配 appId 和 appSecret。appSecret 仅用于本地生成签名，不得放入请求 Header、请求体或日志中。

签名生成步骤如下：

1. 获取当前 Unix 毫秒时间戳 timestamp，其值必须与 X-Openapi-Timestamp 完全一致。
2. 按照 appId + timestamp + appSecret 的顺序直接拼接签名原文，中间不添加分隔符、空格或换行。
3. 使用 UTF-8 编码签名原文，并计算 MD5 摘要。
4. 将摘要转换为 32 位大写十六进制字符串，作为 X-Openapi-Sign 的值。

计算公式：

X-Openapi-Sign = UPPERCASE(MD5_UTF8(appId + timestamp + appSecret))

当前签名只包含 appId、timestamp 和 appSecret，HTTP 方法、请求路径、查询参数及请求体均不参与签名。

3.4.2 签名示例

假设平台分配的认证信息为：

appId     = demo-app
appSecret = demo-secret
timestamp = 1710000000000

签名原文及结果为：

签名原文：demo-app1710000000000demo-secret
MD5：5407ad397c399c6aea299df3a5fe85f5
X-Openapi-Sign：5407AD397C399C6AEA299DF3A5FE85F5

请求 Header 示例：

X-Openapi-App-Id: demo-app
X-Openapi-Timestamp: 1710000000000
X-Openapi-Sign: 5407AD397C399C6AEA299DF3A5FE85F5

Java 签名示例：

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public static String openApiSign(String appId, long timestamp, String appSecret)
        throws NoSuchAlgorithmException {
    String raw = appId + timestamp + appSecret;
    byte[] digest = MessageDigest.getInstance("MD5")
            .digest(raw.getBytes(StandardCharsets.UTF_8));
    char[] hex = "0123456789ABCDEF".toCharArray();
    char[] sign = new char[digest.length * 2];
    for (int i = 0; i < digest.length; i++) {
        int value = digest[i] & 0xFF;
        sign[i * 2] = hex[value >>> 4];
        sign[i * 2 + 1] = hex[value & 0x0F];
    }
    return new String(sign);
}

3.4.3 时间戳与验签要求

• X-Openapi-Timestamp 必须是十进制 Unix 毫秒时间戳，不是秒级时间戳。
• 服务端默认只接受与当前时间相差不超过 5 分钟的请求；实际有效期以部署环境配置为准。
• 三个认证 Header 缺失、应用不存在或已停用、时间戳不合法或过期、签名不一致时，服务端均返回 401 Unauthorized。
• 调用方应确保服务器时钟准确，并为每次请求使用当前时间戳重新计算签名。
• 服务端按大写十六进制字符串进行精确比较，调用方不得发送小写签名。

3.5 幂等规则

• 商品以“当前供应商 + 商品货号”作为业务唯一键。
• 重复提交相同商品货号不会创建第二个商品。
• 修改、删除、价格更新和下架接口重复调用时，应返回当前最终结果，不产生重复数据。

3.6 批量规则

• 批量新增和批量修改接口每次最多提交 500 条商品。
• 请求中的商品货号不能重复。
• 每条商品独立处理，一条商品失败不回滚同一批次中已经成功的其他商品。
• 响应返回接收数量、成功数量、失败数量以及逐条失败数据。
• HTTP 200 OK 表示批次已处理完成，不表示批次内所有商品都成功。
• 请求体结构无效或商品数量超过 500 条时，整个请求返回 400 Bad Request。

3.7 金额规则

• marketPrice 和 discountPrice 使用 JSON 数字类型。
• 单位为人民币元，最多保留两位小数。
• 金额必须大于或等于 0.01。
• 优惠价不得高于市场价。