語言
EN繁简

文件導覽

概覽驗證與簽名Endpoint活動列表建立訂單封存訂單QR Code 解析驗證訂單核銷訂單測試流程

建立訂單

此頁展示簽名接口的 request 與 response 結構，供日後讓商戶系統從伺服器端建立 Yuter 憑證或訂單。

POST/api/integrations/merchant/orders/create

商戶建立訂單接口的結構。

Request 欄位

欄位
類型
必填
說明
customer
object
是
建立訂單所需的客戶資料。
items
array
是
訂單項目或所選憑證方案。
merchantReference
string
否
商戶端對賬用參考編號。

Response 欄位

欄位
類型
說明
code
number
返回代碼。
success
boolean
建立成功時會出現。
orderId
string
已建立的 Yuter 訂單 Id。
bookingId
string
如適用，所建立的憑證 Id。
message
string
可讀訊息。

回傳代碼

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

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

建立訂單 cURL

建立訂單 endpoint 的 request 與 response。

cURL 範例

API_KEY='<raw merchant api key>'
TIMESTAMP=$(($(date +%s) * 1000))
NONCE=$(uuidgen)
BODY='{"customer":{"name":"Test User","email":"test@example.com"},"items":[{"programId":"69ce982e96a5b33a356ab001","variantId":"69ce982e96a5b33a356ab002","quantity":1}],"merchantReference":"ORDER-20260411-001"}'
PATH='/api/integrations/merchant/orders/create'
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": "Order created successfully",
  "orderId": "69ce982e96a5b33a356ac111",
  "bookingId": "69ce982e96a5b33a356abab0"
}