セッショントークンの発行

Customer がストアで注文を作成するための Session Token を発行します。purpose: "portal" を指定すると、自社サイトでサインイン済みの顧客をメール認証なしでストアのカスタマーポータルに入れることもできます。これは API Key 専用のエンドポイントです。

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

認証： API Key

仕組み

サーバーが API Key 認証でこのエンドポイントを呼び出します
短命のセッショントークンを受け取ります
トークンを customer のブラウザに渡します
Customer はトークン（Authorization: Bearer <token>）を使用して注文の作成やチェックアウトを行います

Session Token は単一のストアにスコープされ、自動的に有効期限が切れます。

カスタマーポータルモード

purpose: "portal" を指定すると、自社サイトでサインイン済みの顧客向けにカスタマーポータルへのリンクを取得できます。呼び出し方は同じで、次のルールが変わります：

	`purpose` なし	`purpose: "portal"`
ストア	`storeId` または `productId`	`storeId` が必須。`productId` は 400 で拒否
環境	リクエストごとに `X-Environment` ヘッダーで指定	署名に使った API Key の環境に固定（テストキー → テストのポータルデータ、本番キー → 本番のポータルデータ）。環境フィールドはありません
レスポンス	`token`、`expiresAt`	`token`、`expiresAt`、`portalUrl`

顧客をポータルに送るには、portalUrl に #token=<token> を付け、顧客のブラウザをその URL へ 302 リダイレクトします。SDK のヘルパーはこの URL を組み立てて返します —— サインイン済みの顧客に注文を管理してもらうを参照してください。

ポータルリンクは使い捨てではありません。セッションが有効な間は、リンクを持つ誰もがその顧客としてポータルを開けます。トークンと完全なリンクは bearer 認証情報として扱い、リダイレクト直前にサーバー側で発行し、ログへの記録・保存・メール送信は絶対にしないでください。

ポータルトークンは環境に固定されます。このトークンで Customer Portal API も呼び出す場合は、API Key の環境と一致する X-Environment を送ってください。それ以外の値は 403 Environment mismatch で拒否されます。 purpose を指定しないリクエストの動作は従来とまったく同じです。

リクエストボディ

フィールド	型	必須	説明
`storeId`	string	No	対象ストア ID（Short ID フォーマット `STO_xxx`）。`productId` が指定されていない場合は必須です
`productId`	string	No	商品 ID（Short ID フォーマット `PROD_xxx`）。`storeId` なしで指定した場合、サーバーが商品からストアを自動推定します
`buyerIdentity`	string	Yes	注文帰属のための customer 識別子（例：メールアドレスまたは内部ユーザー ID）。セッション JWT にエンコードされます。ポータルモードでは、その顧客の注文作成時に渡した値と同じである必要があります
`purpose`	string	No	`"portal"` を指定するとカスタマーポータル用のセッションを発行します（カスタマーポータルモードを参照）。チェックアウト用トークンでは省略します

リクエスト例

// 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'])

# カスタマーポータル：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"` の場合のみ。このストアのポータルページ URL（トークンなし）。リダイレクト前に `#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 回）

知っておくべき 2 つの落とし穴

同じ冪等キーでトークンを発行し続けないでください。 繰り返しの呼び出しで同じ X-Idempotency-Key を送ると、プラットフォームの 24 時間キャッシュにヒットして初回のレスポンスが再生され、とうに失効したトークンが返ります。SDK はキーを生成しなくなったため、これはヘッダーを自分で設定した場合（REST を直接呼び出す、または同じ idempotencyKey を 2 回渡す）にのみ起こります。同じ買い手にトークンを繰り返し発行する場合（トークン更新エンドポイント、プラン変更リンク生成など）は、毎回新しいキーを使うか、キーを渡さないでください。 リダイレクト直前に発行してください。 トークンの有効期間は 15 分（スライディング）ですが、checkout / プラン変更セッションはデフォルトで 24 時間です。セッションと同時に発行してキューやメールに置いたトークンは、買い手がクリックする頃には失効しています。プラン変更リンクではトークンを URL fragment に入れます —— 買い手が開くリンクの組み立てを参照してください。

概要

認証

マーチャント API（API Key）

Customer Portal API（Session Token）

GraphQL

セッショントークンの発行

仕組み

カスタマーポータルモード

リクエストボディ

リクエスト例

成功レスポンス (200)

レスポンスフィールド

エラー

知っておくべき 2 つの落とし穴

​仕組み

​カスタマーポータルモード

​リクエストボディ

​リクエスト例

​成功レスポンス (200)

​レスポンスフィールド

​エラー

​知っておくべき 2 つの落とし穴

仕組み

カスタマーポータルモード

リクエストボディ

リクエスト例

成功レスポンス (200)

レスポンスフィールド

エラー

知っておくべき 2 つの落とし穴