請輸入您的 API Token
🗝 序號管理
📊 庫存總覽
排序 類型名稱 ID 可用 即將到期 已出貨 過期 總計 操作
📦 補貨入庫
0 筆
💳 手動出貨
出貨設定
⚠️ 必填且每筆訂單唯一。相同識別碼重複呼叫永遠回傳同一批序號（30天內有效）
💳

填寫左側表單後按取貨

🔍 訂單 / 序號查詢
此頁為唯讀查詢，不會出貨。輸入任意組合篩選條件後按「查詢」，結果顯示在下方。
伺服器端 HMAC 比對，不解密全表
📦 套組管理
套組名稱 ID 可出貨數 組成 操作
👥 帳號管理
ID帳號名稱角色狀態建立時間操作
📋 操作日誌
動作
訂單識別碼
開始日期
結束日期
時間帳號動作類型名稱數量訂單識別碼
🔎 查單
訂單識別碼
整合 ID
開始日期
結束日期
時間整合訂單識別碼Line目標數量
⚙️ 系統設定
🔌 API 整合
Base URL:
Admin/Manual API: Account Token: Authorization: Bearer km_xxx; UI login exchanges token for HttpOnly Session Cookie via POST /api/v1/auth/login.
External Claims: Use Integration Token (not admin/account token). Only calls /api/v1/claims, /api/v1/claims/dry-run, /api/v1/claims/stock.
One-time display: Tokens shown only once at creation/reset/rotation. Store immediately in a secure password manager or Secret Store.
🔐 Auth Methods & Permissions
PurposeToken / CookieEndpoints
Admin, manual restock/dispatchAccount Bearer Token or UI Session Cookie/api/v1/key-types, /api/v1/keys, /api/v1/accounts, /api/v1/integrations, etc.
WooCommerce / Custom site auto-dispatchIntegration Bearer Token (scope: claim)POST /api/v1/claims, POST /api/v1/claims/dry-run
Integration stock queryIntegration Bearer Token (scope: read_stock)GET /api/v1/claims/stock
First admin setupADMIN_BOOTSTRAP_TOKENOnly callable when no active accounts exist; delete Secret after setup
Emergency admin resetADMIN_RECOVERY_TOKENOnly POST /api/v1/recovery/admin-reset
Session Cookie POST/PATCH/DELETE requires X-CSRF-Token; direct Bearer Token API does not need CSRF Header.
POST/api/v1/claims — Integration claims (recommended for WooCommerce / custom sites)
Required: Integration Token with scope claim; API control: claims.create.
Idempotency key: integration_id + external_order_ref + external_line_ref. source and meta for audit/debug only.
Dispatch by key_type_id (no product mapping needed):
curl -s -X POST "$BASE/api/v1/claims"   -H "Authorization: Bearer $INTEGRATION_TOKEN"   -H "Content-Type: application/json"   -d '{"external_order_ref":"wc-order-1001","external_line_ref":"line-1","key_type_id":1,"quantity":1,"source":"woocommerce","meta":{"store":"main"}}'
Response example:
{"data":{"target_type":"key_type","target_id":1,"key_type_id":1,"mapping_id":null,"idempotent":false,"external_order_ref":"wc-order-1001","external_line_ref":"line-1","quantity":1,"keys":["AAAA-BBBB-CCCC"]}}
Dispatch by product/variant/SKU mapping:
curl -s -X POST "$BASE/api/v1/claims"   -H "Authorization: Bearer $INTEGRATION_TOKEN"   -H "Content-Type: application/json"   -d '{"external_order_ref":"wc-order-1002","external_line_ref":"line-1","external_product_id":"123","external_variant_id":"456","quantity":1}'
POST/api/v1/claims/dry-run and GET/api/v1/claims/stock — Test & Stock
/claims/dry-run uses same body as real dispatch, no stock deducted, no daily quota consumed, but per-minute rate limit applies; API control: claims.dry_run.
curl -s -X POST "$BASE/api/v1/claims/dry-run"   -H "Authorization: Bearer $INTEGRATION_TOKEN"   -H "Content-Type: application/json"   -d '{"external_order_ref":"test-order","external_line_ref":"line-1","key_type_id":1,"quantity":1}'
/claims/stock requires Integration Token scope: read_stock; API control: claims.stock.
curl -s -H "Authorization: Bearer $INTEGRATION_TOKEN" "$BASE/api/v1/claims/stock"
🧭 Common Admin Endpoints
EndpointRole / ControlPurpose
POST /api/v1/accountsadmin; bootstrap token for first accountCreate account, returns one-time raw token
POST /api/v1/key-typesadminCreate key type
POST /api/v1/keys/importadmin / restock / operatorRestock, max 1000 keys
POST /api/v1/keys/fetchadmin / fetch / operatorManual dispatch; idempotent replay with api_order_ref
GET /api/v1/keysadmin / operatorQuery key metadata; admin can use include_values=1 (controlled by keys.view_value)
GET /api/v1/keys/:id/valueadmin / operator; keys.view_valueView plaintext key and write to audit log
POST /api/v1/integrationsadmin; integrations.createCreate integration token (one-time raw_token display)
POST /api/v1/integrations/:id/mappingsadmin; integrations.mappings.createMap product/variant/SKU to key_type or bundle
GET /api/v1/system/readinessadminProduction health/security config check
GET /api/v1/system/migrations/statusadmin SessionCheck database version required by app
POST /api/v1/system/migrations/applyadmin Session + CSRFApply backend built-in versioned database upgrades
POST /api/v1/backups/exportadminExport backup JSON (excludes token hash / webhook secret)
POST /api/v1/cleanupadminRun data retention cleanup
⚠️ Common Error Codes (Claims)
codeHTTPMeaning
UNAUTHORIZED401Integration token missing or invalid
INTEGRATION_DISABLED403Integration is not active
MISSING_SCOPE403Missing claim or read_stock scope
IP_NOT_ALLOWED403Source IP not in integration allowlist
VALIDATION_ERROR400Field format error or missing required field
RATE_LIMIT_EXCEEDED429Exceeded per-minute request limit
KEY_TYPE_NOT_FOUND422Specified key_type_id not found
NO_MAPPING_FOUND422No active mapping found for product/variant/SKU
QUOTA_EXCEEDED429Exceeded integration daily claim quota
INSUFFICIENT_STOCK422Insufficient stock
IDEMPOTENCY_CONFLICT409Same order/line already dispatched with different target or quantity
REPLAY_INCOMPLETE409Existing dispatch record cannot be fully replayed, requires manual support
ORDER_EXPIRED410Exceeded 30-day replay window
Production note: Keep KEY_ENCRYPTION_SECRET permanently; existing keys cannot be decrypted after rotation. Delete ADMIN_BOOTSTRAP_TOKEN after creating first admin. Never put admin/account or integration tokens in frontend code or public docs.
📡 Webhook 通知
名稱URL事件狀態操作
當指定類型庫存低於設定閾值時，系統會自動以 POST 傳送 JSON 通知到設定的 URL。
🛡 API 危險操作開關
⚠️ 以下開關由後端強制執行。關閉後即使前端仍有按鈕，後端也會回傳 403 — 所有角色（包括 admin）均受限。
功能名稱 方法 端點路徑 狀態 關閉原因 最後更新 操作
🔗 整合管理
名稱平台狀態 每日配額 速率限制/分 建立時間最後使用操作
🩺 系統維護
🧬 版本與資料庫
載入中…
✅ 上線前檢查
載入中…
💾 備份與匯出
⚠️ 備份檔案包含加密後的序號資料。請妥善保管，勿分享給未授權人員。匯出後請存放於安全位置（如 Google Drive）。
☁️ 雲端備份（R2）

完整資料庫（序號類型、序號、整合、設定——並連同 SubShare 資料庫一起）每日台北 02:00 自動備份到 Cloudflare R2，保留 30 天自動清舊。也可按下方立即備份一次。

📤 匯出備份（下載檔案）
備份檔案不包含：token_hash、webhook_secret、明文序號值。
序號以加密形式（AES-GCM）匯出，還原時需要相同的 KEY_ENCRYPTION_SECRET。
☁️ Google Drive 備份流程

點擊「下載備份」後，可手動將檔案上傳至 Google Drive，或使用以下指令自動化流程：

PowerShell（Windows）
$token = "km_your_admin_token"
$url   = "https://your-worker.workers.dev/api/v1/backups/export"
$body  = '{"include_encrypted_keys":true,"include_audit":true}'
$date  = Get-Date -Format "yyyyMMdd-HHmmss"
$file  = "key-manager-backup-$date.json"

Invoke-RestMethod -Method POST -Uri $url `
  -Headers @{ Authorization="Bearer $token"; "Content-Type"="application/json" } `
  -Body $body -OutFile $file

# Upload to Google Drive folder (requires Google Drive for Desktop mounted)
Copy-Item $file "G:\My Drive\Backups\$file"
Write-Host "Backup saved: $file"
curl（Linux / macOS）
TOKEN="km_your_admin_token"
URL="https://your-worker.workers.dev/api/v1/backups/export"
FILE="key-manager-backup-$(date +%Y%m%d-%H%M%S).json"

curl -s -X POST "$URL"   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{"include_encrypted_keys":true,"include_audit":true}'   -o "$FILE"

echo "Backup saved: $FILE"
# Upload to Google Drive: drag into browser or use rclone
✅ 備份驗證

上傳備份 JSON 檔案以驗證其結構，不會寫入資料庫。