扬卡API网关接入演示

YangCard API Gateway Integration Demo

🔧 API配置

⚠️ 重要： API Key 用于身份认证，API Secret 用于签名计算。两者是不同的密钥！

API Key 在请求头中传输（X-API-Key），API Secret 仅用于本地计算签名，不在网络中传输。

API网关的基础地址
公开密钥，用于身份认证（X-API-Key）
私密密钥，用于签名计算（请妥善保管）

商品接口演示

1. 获取商品目录 🔐 (需要签名)

POST /api/v1/goods/categories

⚠️ 此接口需要签名认证

需要在请求头中添加 X-Timestamp 和 X-Sign

2. 获取商品列表 🔐 (需要签名)

POST /api/v1/goods/list

⚠️ 此接口需要签名认证

需要在请求头中添加 X-Timestamp 和 X-Sign

3. 获取商品详情 🔐 (需要签名)

POST /api/v1/goods/detail

⚠️ 此接口需要签名认证

需要在请求头中添加 X-Timestamp 和 X-Sign

🔐 签名机制说明

签名算法

  1. 将请求参数按key字母升序排序
  2. 序列化为 key1=value1&key2=value2 格式
  3. 拼接签名字符串：apiSecret + timestamp + sortedParams
  4. 使用MD5哈希生成签名（小写十六进制）
  5. 在请求头中添加：
    • X-API-Key: 您的API密钥（用于身份认证）
    • X-Timestamp: 13位毫秒时间戳
    • X-Sign: 计算得到的签名

注意： 签名使用 API Secret 计算，而不是 API Key。API Secret 不应在请求中传输。

示例代码 (JavaScript) - 单商品订单

// 1. 准备参数
const params = { goodsId: 'YC100001', quantity: 1 }
const apiKey = 'yk_...'      // API Key - 用于身份认证
const apiSecret = '40ab...'  // API Secret - 用于签名计算
const timestamp = Date.now()

// 2. 参数排序
const sortedKeys = Object.keys(params).sort()
const sortedParams = sortedKeys.map(k => `${k}=${params[k]}`).join('&')

// 3. 生成签名（使用 apiSecret）
const signStr = apiSecret + timestamp + sortedParams
const sign = CryptoJS.MD5(signStr).toString().toLowerCase()

// 4. 发送请求（使用 apiKey）
fetch('/api/v1/order/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey,      // 传输 API Key
    'X-Timestamp': timestamp.toString(),
    'X-Sign': sign             // 传输签名（不传输 secret）
  },
  body: JSON.stringify(params)
})

示例代码 (JavaScript) - 多商品订单 新

// 多商品订单参数
const params = {
  items: [
    { goodsId: 'YC100001', quantity: 2 },
    { goodsId: 'YC100002', quantity: 1, chargeAccount: '13800138000' }
  ],
  clientOrderNo: 'MY_ORDER_001'
}

// 签名时，数组参数需要 JSON.stringify
const sortedKeys = Object.keys(params).sort()
const sortedParams = sortedKeys.map(k => {
  const v = params[k]
  return `${k}=${typeof v === 'object' ? JSON.stringify(v) : v}`
}).join('&')
// 结果: clientOrderNo=MY_ORDER_001&items=[{"goodsId":"YC100001","quantity":2},{"goodsId":"YC100002","quantity":1,"chargeAccount":"13800138000"}]

const signStr = apiSecret + timestamp + sortedParams
const sign = CryptoJS.MD5(signStr).toString().toLowerCase()

// 发送请求
fetch('/api/v1/order/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey,
    'X-Timestamp': timestamp.toString(),
    'X-Sign': sign
  },
  body: JSON.stringify(params)
})

⚠️ 注意：items 数组的元素顺序必须与请求体一致，否则签名验证失败