Portfolioこの記事について
「ポイントを使う」という行為を、「ポイントを消費してクーポンを発行し、そのクーポンで割引を受ける」という仕組みに置き換えました。その技術的なアーキテクチャを詳しく解説します。
変換処理の全体像
システム間の連携
入力UI、結果表示、コピー機能
処理制御、認証検証、トランザクション
Shopifyクーポン作成API、POSポイント操作API
処理ステップの詳細
顧客からの変換リクエストを受信し、認証を確認
POS APIでリアルタイムの残高を取得し、変換可能か検証
Shopify Admin APIで顧客専用のクーポンを作成
POS APIで指定ポイント分を残高から減算
発行したクーポン情報を顧客のメタフィールドに記録
クーポンコードと詳細情報をフロントエンドに返却
各ステップの詳細
ステップ1-2: リクエスト受付と残高確認
顧客ID: 12345、変換希望ポイント: 500pt、認証トークン: xxx
トークン有効性確認 → OK / 顧客ID所有権確認 → OK
API呼び出し: GET /customers/12345/points → 残高 1250pt
残高(1250) >= 希望(500) → OK / 最小変換単位: 100pt → OK / 変換上限: 10000pt/日 → OK
全てのチェックを通過
ステップ3: Shopifyクーポン生成
Shopify Admin API呼び出し: エンドポイント priceRules + discountCodes
生成されるコード例: 70934-AB12CD-500
レスポンス: priceRuleId, discountCodeId, code
ステップ4: POSポイント減算
重要: 変換を追跡できるよう参照情報（reference）を記録
ステップ5: メタフィールド保存
保存先: 顧客のShopifyメタフィールド（名前空間: loyalty、キー: coupons）
用途: マイページでの一覧表示、使用状況の追跡、取り消し時の参照
トランザクション設計
なぜ順序が重要か
理想の順序: 1. クーポン作成 → 2. ポイント減算 → 3. 記録保存
エラー時のロールバック
補足: メタフィールド保存は「nice to have」。実体（クーポンとポイント）が正しければ運用でカバー可能
API呼び出しの実装ポイント
リトライ戦略
タイムアウト設定
パフォーマンスの考慮
処理時間の内訳
UX対応: 顧客には「処理中...」を表示し、ローディングアニメーションで体感を改善
この設計がもたらす効果
信頼性
- 処理順序の最適化でエラー時の影響を最小化
- ロールバック戦略で不整合を防止
- 全ての処理をログに記録し追跡可能
保守性
- 各ステップが独立しておりテストしやすい
- エラー原因の特定が容易
- 将来の機能追加（ポイント還元率変更など）に対応しやすい