语言
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,
  };
}