語言
EN繁简

文件導覽

概覽驗證與簽名EndpointQR Code 解析驗證訂單核銷訂單測試流程

驗證與簽名

每個請求都需要商戶串接金鑰及 HMAC SHA256 簽名。缺少 header、簽名錯誤、timestamp 過期或 nonce 重複都會被拒絕。

  • 演算法：HMAC SHA256
  • 密鑰：原始串接金鑰
  • 輸出格式：小寫 hex 字串
  • 時間窗：5 分鐘
  • Nonce：每個請求必須唯一
  • 此 API 採用 RESTful 風格，以 HTTP POST + JSON body 傳送。

Headers

Header
必填
範例值
說明
Content-Type
是
application/json
JSON request body。
x-api-key
是
<merchant_api_key>
由 Yuter 簽發的原始串接金鑰。
x-timestamp
是
<unix_ms>
Unix 毫秒時間戳。超過 5 分鐘的請求會被拒絕。
x-nonce
是
<unique_random_string>
每個請求都必須唯一。重複 nonce 會被拒絕。
x-signature
是
<hex_hmac_sha256>
以 method、path、timestamp、nonce 及 raw JSON body 組成的 HMAC SHA256 簽名。

簽名 payload

POST
/api/integrations/merchant/bookings/redeem
<timestamp>
<nonce>
{"bookingId":"<booking_id>"}

請使用完全一致的 HTTP method、request path、timestamp、nonce 及原始 JSON body。簽名所用的 JSON body 必須與實際送出的 body 完全一致。

RESTful 請求範例

POST /api/integrations/merchant/bookings/redeem HTTP/1.1
Host: www.yuterwellness.com
Content-Type: application/json
x-api-key: <merchant_api_key>
x-timestamp: <unix_ms>
x-nonce: <unique_random_string>
x-signature: <hex_hmac_sha256>

{"bookingId":"69ce982e96a5b33a356abab0"}

Node.js 簽名範例

import crypto from 'crypto';

function buildSigningPayload({ method, path, timestamp, nonce, body }) {
  return [method.toUpperCase(), path, timestamp, nonce, body].join('\n');
}

function createMerchantRequest({ apiKey, bookingId }) {
  const path = '/api/integrations/merchant/bookings/redeem';
  const method = 'POST';
  const timestamp = String(Date.now());
  const nonce = crypto.randomUUID();
  const body = JSON.stringify({ bookingId });

  const signature = crypto
    .createHmac('sha256', apiKey)
    .update(buildSigningPayload({ method, path, timestamp, nonce, body }))
    .digest('hex');

  return {
    url: `https://www.yuterwellness.com${path}`,
    method,
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
      'x-timestamp': timestamp,
      'x-nonce': nonce,
      'x-signature': signature,
    },
    body,
  };
}