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