公共约定

curl -X GET https://api.sp.airgoe.com/api/v2/client/profile \
  -H "X-API-Key: sk-your-api-key-here"

{
  "success": true,
  "data": { ... }
}

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  }
}

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "可读的错误描述"
}

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "参数校验失败",
  "details": {
    "field": "cargo.weight",
    "reason": "weight 必须为正数"
  }
}

curl -X POST https://api.sp.airgoe.com/api/v2/orders \
  -H "X-API-Key: sk-your-api-key" \
  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{ "quotationId": "QT20260310100001" }'

const crypto = require('crypto');

function verifyWebhookSignature(secret, timestamp, body, signature) {
  const payload = timestamp + '.' + body;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  // 常量时间比较，防止时序攻击
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// 在 Webhook 处理函数中：
app.post('/webhooks/sp', (req, res) => {
  const timestamp = req.headers['x-webhook-timestamp'];
  const signature = req.headers['x-webhook-signature'];
  const body = JSON.stringify(req.body);

  if (!verifyWebhookSignature(WEBHOOK_SECRET, timestamp, body, signature)) {
    return res.status(401).send('Invalid signature');
  }

  // 处理 Webhook 事件...
  const { eventType, orderId, data } = req.body;

  res.status(200).send('OK');
});