語言
EN繁简

文件導覽

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

QR Code 解析

當商戶職員直接掃描客人的 QR code 時，可呼叫此 endpoint。商戶只需把掃描器讀到的原始字串傳給 Yuter，Yuter 會驗證 QR token、解析 booking，並確認該 booking 屬於此商戶。

POST/api/integrations/merchant/bookings/resolve-qr

把已掃描的 Yuter QR code 解析成此商戶可處理的 booking。

Request 欄位

欄位
類型
必填
說明
qrCode
string
是
QR 掃描器讀出的原始字串，請原樣送出。

Response 欄位

欄位
類型
說明
code
number
返回代碼。
success
boolean
QR code 成功解析時會出現。
message
string
可讀訊息。
bookingId
string
解析後的 MongoDB booking id，可用於後續 validate 或 redeem。
booking
object
QR code 解析成功後回傳的訂單摘要。
qr
object
QR 相關資料，例如 tokenAgeMs。
reason
string
code 4 時的受控錯誤原因。

回傳代碼

為了讓商戶文件及收銀員介面更簡單，Yuter 將此整合回應統一成四個頂層代碼。

代碼
意思
備註
1
成功
訂單驗證成功或已成功核銷。
2
已核銷
此訂單在本次請求前已完成核銷。
3
無效訂單
booking id 無效，或找不到相關訂單。
4
其他錯誤
認證失敗、不可核銷、商戶無權限，或其他受控錯誤。

QR Code 解析範例

QR Code 解析 endpoint 的 request 與 response 範例。

cURL 範例

API_KEY='<raw merchant api key>'
SCANNED_QR='<掃描器讀到的原始 qr 字串>'
TIMESTAMP=$(($(date +%s) * 1000))
NONCE=$(uuidgen)
BODY='{"qrCode":"'"$SCANNED_QR"'"}'
PATH='/api/integrations/merchant/bookings/resolve-qr'
PAYLOAD="POST
$PATH
$TIMESTAMP
$NONCE
$BODY"
SIGNATURE=$(printf "%s" "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_KEY" -hex | sed 's/^.* //')

curl -X POST "https://www.yuterwellness.com$PATH" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-nonce: $NONCE" \
  -H "x-signature: $SIGNATURE" \
  -d "$BODY"

回應範例

{
  "code": 1,
  "success": true,
  "message": "QR code resolved successfully",
  "bookingId": "69ce982e96a5b33a356abab0",
  "booking": {
    "_id": "69ce982e96a5b33a356abab0",
    "programTitle": "Private Merchant Test Event",
    "userName": "Test User",
    "userEmail": "test@example.com",
    "quantity": 1,
    "date": "2026-04-10",
    "status": "paid"
  },
  "qr": {
    "tokenAgeMs": 1834
  }
}