签发 Session Token

为 customer 签发 Session Token 以在您的门店中创建订单；或传 purpose: "portal"，让已在您站点登录的顾客免邮箱验证进入您门店的客户门户。这是 API Key 专属 端点。

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

认证方式： API Key

工作原理

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

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

客户门户模式

传 purpose: "portal"，为已在您站点登录的顾客获取客户门户链接。调用方式不变，以下规则不同：

	不传 `purpose`	`purpose: "portal"`
门店	`storeId` 或 `productId`	必须传 `storeId`；传 `productId` 返回 400
环境	每次请求由 `X-Environment` 请求头决定	固定为签名所用 API Key 的环境（测试 Key → 测试门户数据，生产 Key → 生产门户数据）。没有环境字段
响应	`token`、`expiresAt`	`token`、`expiresAt`、`portalUrl`

要让顾客进入门户，把 #token=<token> 拼到 portalUrl 后面，并用 302 把顾客浏览器重定向到拼好的地址。SDK 辅助方法会替您拼好 —— 见让已登录顾客管理订单。

门户链接不是一次性的。会话存活期间，任何持有链接的人都能以该顾客身份打开门户。请把 token 与完整链接当作 bearer 凭证：在服务端、临跳转前签发，绝不写入日志、不存储、不通过邮件发送。

门户 token 绑定其环境。若您还用它调用 Customer Portal API，X-Environment 必须与 API Key 的环境一致；其他值返回 403 Environment mismatch。不传 purpose 的请求行为与以前完全一致。

请求体

字段	类型	必需	说明
`storeId`	string	否	目标门店 ID（Short ID 格式 `STO_xxx`）。与 `productId` 至少传一个
`productId`	string	否	产品 ID（Short ID 格式 `PROD_xxx`）。提供时可省略 `storeId`，服务端自动从产品反查门店
`buyerIdentity`	string	是	Customer 身份标识（例如邮箱或内部用户 ID），用于订单归属。写入会话 JWT。门户模式下必须与创建该顾客订单时传入的值相同
`purpose`	string	否	设为 `"portal"` 时签发客户门户会话（见客户门户模式）。签发收银台 token 时不传

请求示例

// 使用 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",
});

// 客户门户链接（以 purpose: "portal" 调用本端点；
// portalUrl 已带 #token=...）
const { portalUrl } = await client.auth.createCustomerPortalLink({
  storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
  buyerIdentity: "user_8f3a2c",
});

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"

MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"storeId":"STO_2aUyqjCzEIiEcYMKj7TZtw","buyerIdentity":"user_8f3a2c","purpose":"portal"}'
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'])

# 客户门户：把 token 拼到 portalUrl 后，再用 302 跳转浏览器
result = call_api_with_signature('POST', '/v1/actions/auth/issue-session-token', {
    'storeId': 'STO_2aUyqjCzEIiEcYMKj7TZtw',
    'buyerIdentity': 'user_8f3a2c',
    'purpose': 'portal'
})
redirect_url = result['data']['portalUrl'] + '#token=' + result['data']['token']

成功响应 (200)

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

purpose: "portal" 时：

{
  "data": {
    "token": "opaque-session-token...",
    "expiresAt": "2024-01-15T11:00:00.000Z",
    "portalUrl": "https://pancake.waffo.ai/consumer/portal/store/STO_2aUyqjCzEIiEcYMKj7TZtw"
  }
}

响应字段

字段	类型	说明
`token`	string	Session Token
`expiresAt`	string	会话保持闲置时的过期时间（ISO 8601）。会话有效期 15 分钟，每次使用都会续期，因此活跃会话会活过这个时间点
`portalUrl`	string	仅 `purpose` 为 `"portal"` 时返回。该门店的门户页面地址，不含 token。跳转前拼上 `#token=<token>`

错误响应

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

状态码	`errors[0].message`	含义	推荐处理
400	`Missing required field: buyerIdentity`	`buyerIdentity` 缺失或为空	修正请求体后重新提交
400	`Missing required field: provide storeId or productId`	`storeId` 和 `productId` 都未提供	至少提供其中一个后重新提交
400	`purpose=portal requires storeId and does not accept productId`	`purpose` 为 `"portal"` 且传了 `productId`（无论是否传了 `storeId`）	只传 `storeId`（不传 `productId`）后重新提交
400	`Invalid purpose: expected "portal"`	`purpose` 的取值不是 `"portal"`	将 `purpose` 设为 `"portal"` 或不传，然后重新提交
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 次）

两个值得知道的坑

不要用同一个幂等键反复签发令牌。 重复调用时发送同一个 X-Idempotency-Key 会命中平台的 24 小时幂等缓存 —— 拿回的是第一次的响应，里面的令牌早已过期。SDK 已不再自行生成键，因此这只会发生在你自己设置该请求头时（直连 REST，或两次传了同一个 idempotencyKey）。如果你会为同一买家反复签发令牌（令牌刷新端点、换方案链接生成器），每次用新的键，或干脆不传。 跳转前再签发。 令牌 15 分钟有效（滑动续期），而 checkout / 换方案会话默认有 24 小时。与会话同时签发、然后在队列或邮件里放着的令牌，等买家点开时早就死了。换方案链接的令牌放 URL fragment —— 见构造给买家打开的链接。

概览

认证

商户 API（API Key）

Customer Portal API（Session Token）

GraphQL

工作原理

客户门户模式

请求体

请求示例

成功响应 (200)

响应字段

错误响应

两个值得知道的坑

​工作原理

​客户门户模式

​请求体

​请求示例

​成功响应 (200)

​响应字段

​错误响应

​两个值得知道的坑

工作原理

客户门户模式

请求体

请求示例

成功响应 (200)

响应字段

错误响应

两个值得知道的坑