签发 Session Token - Waffo Pancake

为 customer 签发 Session Token 以在您的门店中创建订单。这是 API Key 专属 端点。

POST /v1/actions/auth/issue-session-token

认证方式： API Key

工作原理

您的服务器使用 API Key 认证调用此端点
获取一个短效 Session Token
将 Token 传递给 customer 的浏览器
Customer 使用 Token（Authorization: Bearer <token>）创建订单和进行收银台交互

Session Token 限定于单个门店，自动过期。

请求体

字段	类型	必需	说明
`storeId`	string	否	目标门店 ID（Short ID 格式 `STO_xxx`）。与 `productId` 至少传一个
`productId`	string	否	产品 ID（Short ID 格式 `PROD_xxx`）。提供时可省略 `storeId`，服务端自动从产品反查门店
`buyerIdentity`	string	是	Customer 身份标识（例如邮箱或内部用户 ID），用于订单归属。写入会话 JWT

请求示例

// 使用 storeId
const { token, expiresAt } = await client.auth.issueSessionToken({
  storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
  buyerIdentity: "customer@example.com",
});

// 使用 productId（自动推导 storeId）
const { token, expiresAt } = await client.auth.issueSessionToken({
  productId: "PROD_7J3K5L8M2N4P6Q9R",
  buyerIdentity: "customer@example.com",
});

MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"storeId":"STO_2aUyqjCzEIiEcYMKj7TZtw","buyerIdentity":"customer@example.com"}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 | tr -d '\n')
CANONICAL_REQUEST="POST
/v1/actions/auth/issue-session-token
$TIMESTAMP
$BODY_HASH"

SIGNATURE=$(echo -n "$CANONICAL_REQUEST" | openssl dgst -sha256 -sign private_key.pem | base64 | tr -d '\n')

curl -X POST "https://api.waffo.ai/v1/actions/auth/issue-session-token" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $MERCHANT_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"productId":"PROD_7J3K5L8M2N4P6Q9R","buyerIdentity":"customer@example.com"}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 | tr -d '\n')
CANONICAL_REQUEST="POST
/v1/actions/auth/issue-session-token
$TIMESTAMP
$BODY_HASH"

SIGNATURE=$(echo -n "$CANONICAL_REQUEST" | openssl dgst -sha256 -sign private_key.pem | base64 | tr -d '\n')

curl -X POST "https://api.waffo.ai/v1/actions/auth/issue-session-token" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $MERCHANT_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

# 使用 storeId
result = call_api_with_signature('POST', '/v1/actions/auth/issue-session-token', {
    'storeId': 'STO_2aUyqjCzEIiEcYMKj7TZtw',
    'buyerIdentity': 'customer@example.com'
})

# 使用 productId
result = call_api_with_signature('POST', '/v1/actions/auth/issue-session-token', {
    'productId': 'PROD_7J3K5L8M2N4P6Q9R',
    'buyerIdentity': 'customer@example.com'
})
print(result['data']['token'])

成功响应 (200)

{
  "data": {
    "token": "opaque-session-token...",
    "expiresAt": "2024-01-15T11:00:00.000Z"
  }
}

响应字段

字段	类型	说明
`token`	string	Session Token
`expiresAt`	string	过期时间（ISO 8601）

错误响应

重试策略：4xx 一律不要重试 — 修正请求后重发。5xx 指数退避重试（起步 5s，最多 3 次）。

状态码	`errors[0].message`	含义	推荐处理
400	`Missing required field: buyerIdentity`	`buyerIdentity` 缺失或为空	修正请求体后重新提交
400	`Missing required field: provide storeId or productId`	`storeId` 和 `productId` 都未提供	至少提供其中一个后重新提交
400	`Expected format: STO_xxx, got "..."`	`storeId` Short ID 解码失败	修正 `storeId` 格式后重新提交
400	`Expected format: PROD_xxx, got "..."`	`productId` Short ID 解码失败	修正 `productId` 格式后重新提交
400	`Store is not active`	门店存在但状态非 `active`	激活门店后重新提交
401	`Missing merchantId in request context`	API Key 认证未解析出 merchant	检查 API Key 请求头与签名
403	`Access denied: you do not have permission to this store`	商户不拥有该门店	验证门店归属
404	`Store not found`	门店不存在或已删除	验证 store ID
404	`Product not found`	产品不存在	验证 product ID
500	`Internal server error`	服务端意外失败	指数退避重试（起步 5s，最多 3 次）

⌘I