{ "openapi": "3.0.3", "info": { "title": "號卡平台渠道 API", "version": "0.24.0", "description": "統一入口：https://api.roguemobile.hk/v1。每次請求發送 X-Partner-Id（渠道帳戶）和 X-API-Key（固定金鑰），無需取得或更新臨時 token。點擊「設定授權」分別填寫這兩個值。\n\n常用流程：查詢地區套餐目錄 → 提交啟用、續費或重新啟用 → 查單或接收回呼。啟用用 catalog_entry_id 自動匹配套餐和地址；續費、重新啟用用號碼或 ICCID，續費預設原套餐和 IMMEDIATE。\n\n辦理使用平台已登記的號卡、套餐、地址及渠道報價，不在提交前逐卡查詢線路或再次查詢套餐目錄。查詢與資料同步介面可按需單獨呼叫，不是辦理前置步驟。\n\n業務批次使用 items[]、defaults；每批至少一張已歸屬本渠道的卡，不設固定條數上限。平台在提交前按整批渠道售價檢查餘額，不凍結資金。僅最終 succeeded 明細扣款；失敗不扣款，結果未確認不重複提交。本渠道前序扣費任務未完成時，後續扣費任務排隊，發送前再次檢查餘額。免費 WFC 與其他卡的收費業務互不阻塞；同一卡片的未完成業務仍互斥。\n\n每批生成一個任務；通過 GET /jobs/{id}、GET /jobs?txid=... 或回呼讀取結果。HTTP 202 只代表已受理。網路異常先查原 txid；不要換 txid 盲目重發收費業務。\n\n請求上限為每渠道每分鐘 120 次，已認證任務 GET 查單不占此額度。請求體不超過 200,000 位元組。平台限額或服務擁堵可能延後處理。" }, "servers": [ { "url": "https://api.roguemobile.hk/v1", "description": "渠道統一入口" } ], "tags": [ { "name": "業務辦理" }, { "name": "任務" }, { "name": "庫存與地區" }, { "name": "查詢" }, { "name": "套餐" }, { "name": "帳戶與帳單" }, { "name": "相容接入" } ], "components": { "securitySchemes": { "channelAccount": { "type": "apiKey", "in": "header", "name": "X-Partner-Id", "description": "渠道帳戶，即平台分配的渠道代碼；與 X-API-Key 同時發送。" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "平台發放的固定 API Key，直接填寫原值，不加 Bearer 前綴。不會定時到期；重置金鑰後舊值立即失效。" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "insufficient_balance", "forbidden", "not_found", "conflict", "rate_limited", "internal_error", "upstream_error", "unavailable" ] }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message", "details" ] }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "error", "meta" ] }, "Meta": { "type": "object", "properties": { "request_id": { "type": "string", "description": "請求追蹤號，排障時提供。" }, "job_id": { "type": "string" }, "txid": { "type": "string", "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" } }, "required": [ "request_id" ] }, "ServiceStatus": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "operational" ] }, "timestamp": { "type": "string", "format": "date-time" }, "mode": { "type": "string", "enum": [ "mock", "live" ] } } }, "Token": { "type": "object", "properties": { "token": { "type": "string", "description": "存取權杖，後續請求發送 `Authorization: Bearer `。" }, "expires_in": { "type": "integer", "example": 1800, "description": "權杖有效秒數，目前為 1800。" }, "token_type": { "type": "string", "example": "Bearer", "description": "Bearer" } } }, "Plan": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "介面套餐 ID，從目錄讀取。續費換套餐時與 plan_change=true 配合。" }, "plan_code": { "type": "string", "description": "介面套餐代碼，從 /plans 或地區套餐目錄讀取；不要使用套餐展示名稱代替。" }, "plan_name": { "type": "string" }, "cost": { "type": "string", "nullable": true, "example": null, "description": "相容保留欄位，目前為 null；渠道結算報價讀取 price、prices 或訂單 billing。" }, "price": { "type": "string", "nullable": true, "description": "目前渠道該套餐的單週期續費價（美元字串）；未設定續費價時為 null，其他業務報價請讀取 prices。" }, "prices": { "type": "object", "description": "按業務與卡類型列出的渠道售價（美元字串），null 表示未設定。", "properties": { "activate_physical_price": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2.60", "nullable": true }, "activate_esim_price": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2.60", "nullable": true }, "renew_price": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2.60", "nullable": true }, "reactivate_price": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2.60", "nullable": true } } }, "product_code": { "type": "string", "description": "平台產品編號，用於目錄篩選；不能代替業務請求的 plan_code。" }, "currency": { "type": "string", "enum": [ "USD" ] } } }, "CustomerLine": { "type": "object", "properties": { "found": { "type": "boolean" }, "mdn": { "type": "string", "description": "10 位美國手機號碼，不帶 +1、空格或連字符。" }, "esn": { "type": "string", "nullable": true, "description": "已分配給本渠道的 ICCID，使用字串保存。" }, "sim": { "type": "string", "nullable": true }, "customer_id": { "type": "string", "nullable": true }, "enrollment_id": { "type": "string", "nullable": true, "description": "已登記線路的 Enrollment ID，可單獨用於識別線路；若同時提供 ICCID 或手機號碼，必須指向同一線路。" }, "account_number": { "type": "string", "nullable": true }, "plan_id": { "type": "string", "nullable": true, "description": "介面套餐 ID，從目錄讀取。續費換套餐時與 plan_change=true 配合。" }, "plan_code": { "type": "string", "nullable": true, "description": "介面套餐代碼，從 /plans 或地區套餐目錄讀取；不要使用套餐展示名稱代替。" }, "plan_name": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true, "description": "五位美國郵政編碼字串，保留前導 0。" }, "city": { "type": "string", "nullable": true, "description": "城市。" }, "state": { "type": "string", "nullable": true, "description": "美國州的兩位字母代碼。" }, "address": { "type": "string", "nullable": true, "description": "真實街道地址。" }, "address_two": { "type": "string", "nullable": true, "description": "地址補充資訊。" }, "wfc_address": { "type": "string", "nullable": true }, "wfc_address_two": { "type": "string", "nullable": true }, "wfc_city": { "type": "string", "nullable": true }, "wfc_state": { "type": "string", "nullable": true }, "wfc_zip": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "first_name": { "type": "string", "nullable": true, "description": "名（可選）。" }, "last_name": { "type": "string", "nullable": true, "description": "姓（可選）。" }, "email": { "type": "string", "nullable": true, "description": "電子郵件（可選）。" }, "message": { "type": "string", "nullable": true }, "timestamp": { "type": "string", "format": "date-time" } } }, "InventoryStatus": { "type": "object", "properties": { "esn": { "type": "string", "description": "已分配給本渠道的 ICCID，使用字串保存。" }, "status": { "type": "string", "enum": [ "FREE", "NOTFOUND", "ACTIVE", "ERROR" ] }, "message": { "type": "string" }, "code": { "type": "string", "nullable": true }, "esn_status": { "type": "string", "nullable": true }, "provision_status": { "type": "string", "nullable": true }, "mdn": { "type": "string", "nullable": true, "description": "10 位美國手機號碼，不帶 +1、空格或連字符。" }, "enrollment_id": { "type": "string", "nullable": true, "description": "已登記線路的 Enrollment ID，可單獨用於識別線路；若同時提供 ICCID 或手機號碼，必須指向同一線路。" }, "zip": { "type": "string", "nullable": true, "description": "五位美國郵政編碼字串，保留前導 0。" }, "plan_code": { "type": "string", "nullable": true, "description": "介面套餐代碼，從 /plans 或地區套餐目錄讀取；不要使用套餐展示名稱代替。" }, "plan_name": { "type": "string", "nullable": true }, "timestamp": { "type": "string", "format": "date-time" } } }, "Job": { "type": "object", "properties": { "id": { "type": "string", "example": "ord_example" }, "txid": { "type": "string", "example": "order-99", "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" }, "partner_id": { "type": "string", "description": "平台分配的渠道代碼。" }, "type": { "type": "string", "enum": [ "activation", "renewal", "reactivation", "wifi_calling" ] }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "partial" ] }, "totals": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "succeeded": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 } }, "required": [ "total", "succeeded", "failed", "pending" ] }, "defaults": { "type": "object", "description": "批次預設值。啟用必須具備完整真實地址（街道、城市、州、ZIP）；明細 customer、zip 可覆蓋。重新啟用和 WFC 地址可選，優先本次明確欄位，再使用本地號卡已登記地址、同卡最近成功開卡地址；本地無有效地址時由線路目前 WFC 或服務記錄補齊，不按城市或郵編從目錄任選地址。可選姓名、電子郵件、address_two 的空字串按未填處理。" }, "webhook_url": { "type": "string", "nullable": true, "description": "可選，本任務的渠道回呼 HTTPS 地址，覆蓋後台登記地址。不要填 API 地址；省略時使用已登記的渠道回呼地址。" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "billing": { "type": "object", "description": "批次報價與已扣款金額。", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2.60" }, "charged_amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2.60", "description": "已確認成功並記帳的金額；受理、排隊、結果未確認及失敗均不扣款。" }, "currency": { "type": "string", "enum": [ "USD" ] } } }, "paused": { "type": "boolean", "description": "true 表示排隊後餘額不足暫停；儲值後呼叫 resume。" }, "attention_required": { "type": "boolean", "description": "長期未完成，需要核實；系統仍每五分鐘查詢原任務，可用 recheck 提前補查。" }, "reason": { "type": "string", "enum": [ "INSUFFICIENT_BALANCE" ] } }, "required": [ "id", "txid", "partner_id", "type", "status", "totals", "billing" ] }, "JobItem": { "type": "object", "properties": { "id": { "type": "string", "example": "item_example" }, "job_id": { "type": "string" }, "txid": { "type": "string", "example": "order-99_56789012", "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" }, "job_txid": { "type": "string", "example": "order-99", "description": "批次的渠道交易號。" }, "esn": { "type": "string", "nullable": true, "description": "已分配給本渠道的 ICCID，使用字串保存。" }, "status": { "type": "string", "enum": [ "pending", "processing", "succeeded", "failed" ] }, "plan_code": { "type": "string", "nullable": true, "description": "介面套餐代碼，從 /plans 或地區套餐目錄讀取；不要使用套餐展示名稱代替。" }, "plan_id": { "type": "string", "nullable": true, "description": "介面套餐 ID，從目錄讀取。續費換套餐時與 plan_change=true 配合。" }, "zip": { "type": "string", "nullable": true, "description": "五位美國郵政編碼字串，保留前導 0。" }, "request": { "type": "object", "nullable": true }, "result": { "type": "object", "nullable": true, "description": "已確認的逐卡業務結果，保留到期日等返回欄位；欄位可能因業務不同而省略，不推算未返回的日期。" }, "last_error": { "type": "string", "nullable": true, "description": "最近的錯誤說明。" }, "attempt_count": { "type": "integer", "description": "該明細的處理嘗試次數。" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "finished_at": { "type": "string", "format": "date-time", "nullable": true, "description": "處理完成時間；可能為 null。這不是服務到期日。" }, "created_at": { "type": "string", "format": "date-time" }, "billing": { "type": "object", "description": "本條報價及成功扣款金額。", "properties": { "price": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2.60" }, "charged_amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "2.60", "description": "已確認成功並記帳的金額；受理、排隊、結果未確認及失敗均不扣款。" }, "currency": { "type": "string", "enum": [ "USD" ] } } } }, "required": [ "id", "job_id", "job_txid", "txid", "esn", "status", "result", "billing" ] }, "JobDetail": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/Job" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/JobItem" } }, "match": { "type": "string", "enum": [ "job_id", "txid", "item_txid" ], "description": "匹配方式為任務 ID 或交易號；交易號可對應批次或逐卡明細。" } }, "required": [ "job", "items" ] }, "ActivationItem": { "type": "object", "properties": { "esn": { "type": "string", "minLength": 18, "description": "已分配給本渠道的 ICCID，使用字串保存。", "pattern": "^[0-9]{18,22}$", "maxLength": 22 }, "mdn": { "type": "string", "description": "10 位美國手機號碼，不帶 +1、空格或連字符。", "pattern": "^[0-9]{10}$" }, "plan_code": { "type": "string", "description": "介面套餐代碼，從 /plans 或地區套餐目錄讀取；不要使用套餐展示名稱代替。", "minLength": 1, "maxLength": 100 }, "zip": { "type": "string", "pattern": "^\\d{5}$", "description": "五位美國郵政編碼字串，保留前導 0。" }, "customer": { "type": "object", "properties": { "first_name": { "type": "string", "description": "名（可選）。", "maxLength": 250 }, "last_name": { "type": "string", "description": "姓（可選）。", "maxLength": 250 }, "email": { "type": "string", "description": "電子郵件（可選）。", "maxLength": 250 }, "address": { "type": "string", "description": "真實街道地址。", "minLength": 1, "maxLength": 200 }, "city": { "type": "string", "description": "城市。", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "description": "美國州的兩位字母代碼。", "minLength": 1, "maxLength": 2, "pattern": "^[A-Za-z]{2}$" }, "zip": { "type": "string", "pattern": "^\\d{5}$", "description": "五位美國郵政編碼字串，保留前導 0。", "minLength": 1, "maxLength": 5 } }, "description": "目前明細的客戶資料或地址，覆蓋批次 defaults。", "additionalProperties": false }, "catalog_entry_id": { "type": "string", "description": "可選便捷辦理欄位，從地區套餐目錄讀取，自動匹配套餐代碼及完整地址；與 plan_code 同傳時必須一致。", "minLength": 1, "maxLength": 250 }, "catalog_revision": { "type": "string", "description": "可選目錄版本；目錄變更時拒絕舊版本，重新讀取後提交。", "minLength": 1, "maxLength": 250 } }, "anyOf": [ { "required": [ "plan_code" ] }, { "required": [ "catalog_entry_id" ] } ], "allOf": [ { "anyOf": [ { "required": [ "esn" ] }, { "required": [ "mdn" ] } ] } ], "additionalProperties": false }, "ActivationRequest": { "type": "object", "required": [ "items" ], "properties": { "txid": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]{1,64}$", "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ActivationItem" }, "minItems": 1 }, "defaults": { "type": "object", "properties": { "enrollment_type": { "type": "string", "enum": [ "HANDOVER", "SHIPMENT" ], "default": "HANDOVER", "description": "HANDOVER（預設）：卡已在使用者手中；SHIPMENT：待寄送。", "minLength": 1, "maxLength": 250 }, "carrier": { "type": "string", "example": "TMB", "description": "網路代碼；目前僅開放 TMB。", "minLength": 1, "maxLength": 250, "enum": [ "TMB" ] }, "first_name": { "type": "string", "description": "名（可選）。", "maxLength": 250 }, "last_name": { "type": "string", "description": "姓（可選）。", "maxLength": 250 }, "email": { "type": "string", "description": "電子郵件（可選）。", "maxLength": 250 }, "address": { "type": "string", "example": "125 East Main St", "description": "真實街道地址。", "minLength": 1, "maxLength": 200 }, "city": { "type": "string", "example": "Rochester", "description": "城市。", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "example": "NY", "description": "美國州的兩位字母代碼。", "minLength": 1, "maxLength": 2, "pattern": "^[A-Za-z]{2}$" }, "zip": { "type": "string", "pattern": "^\\d{5}$", "example": "14604", "description": "五位美國郵政編碼字串，保留前導 0。", "minLength": 1, "maxLength": 5 } }, "description": "批次預設值。啟用必須具備完整真實地址（街道、城市、州、ZIP）；明細 customer、zip 可覆蓋。重新啟用和 WFC 地址可選，優先本次明確欄位，再使用本地號卡已登記地址、同卡最近成功開卡地址；本地無有效地址時由線路目前 WFC 或服務記錄補齊，不按城市或郵編從目錄任選地址。可選姓名、電子郵件、address_two 的空字串按未填處理。", "additionalProperties": false }, "mode": { "type": "string", "enum": [ "sync", "async" ], "description": "async（預設）排隊處理，未完成返回 202；若全部明細在本地校驗時已失敗，可直接返回 200。sync 嘗試立即辦理，整批已有最終結果返回 200，否則返回 202。200 不代表業務成功；均以最終逐卡狀態為準。", "default": "async" }, "webhook_url": { "type": "string", "format": "uri", "description": "可選，本任務的渠道回呼 HTTPS 地址，覆蓋後台登記地址。不要填 API 地址；省略時使用已登記的渠道回呼地址。" } }, "example": { "txid": "channel-activation-001", "items": [ { "esn": "89000000000000000001", "catalog_entry_id": "CATALOG_ENTRY_ID" } ] }, "additionalProperties": false }, "ReactivationRequest": { "type": "object", "required": [ "items" ], "properties": { "txid": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]{1,64}$", "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" }, "items": { "type": "array", "items": { "type": "object", "properties": { "esn": { "type": "string", "description": "已分配給本渠道的 ICCID，使用字串保存。", "pattern": "^[0-9]{18,22}$", "minLength": 18, "maxLength": 22 }, "mdn": { "type": "string", "description": "10 位美國手機號碼，不帶 +1、空格或連字符。", "pattern": "^[0-9]{10}$" }, "enrollment_id": { "type": "string", "description": "已登記線路的 Enrollment ID，可單獨用於識別線路；若同時提供 ICCID 或手機號碼，必須指向同一線路。", "minLength": 1, "maxLength": 100 }, "zip": { "type": "string", "pattern": "^\\d{5}$", "description": "五位美國郵政編碼字串，保留前導 0。" }, "customer": { "type": "object", "properties": { "address": { "type": "string", "description": "真實街道地址。", "minLength": 1, "maxLength": 200 }, "address_two": { "type": "string", "description": "地址補充資訊。", "maxLength": 250 }, "city": { "type": "string", "description": "城市。", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "description": "美國州的兩位字母代碼。", "minLength": 1, "maxLength": 2, "pattern": "^[A-Za-z]{2}$" }, "zip": { "type": "string", "pattern": "^\\d{5}$", "description": "五位美國郵政編碼字串，保留前導 0。", "minLength": 1, "maxLength": 5 } }, "description": "目前明細的客戶資料或地址，覆蓋批次 defaults。", "additionalProperties": false } }, "additionalProperties": false, "anyOf": [ { "required": [ "esn" ] }, { "required": [ "mdn" ] }, { "required": [ "enrollment_id" ] } ] }, "minItems": 1 }, "defaults": { "type": "object", "properties": { "address": { "type": "string", "description": "真實街道地址。", "minLength": 1, "maxLength": 200 }, "address_two": { "type": "string", "description": "地址補充資訊。", "maxLength": 250 }, "city": { "type": "string", "description": "城市。", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "description": "美國州的兩位字母代碼。", "minLength": 1, "maxLength": 2, "pattern": "^[A-Za-z]{2}$" }, "zip": { "type": "string", "pattern": "^\\d{5}$", "description": "五位美國郵政編碼字串，保留前導 0。", "minLength": 1, "maxLength": 5 } }, "description": "批次預設值。啟用必須具備完整真實地址（街道、城市、州、ZIP）；明細 customer、zip 可覆蓋。重新啟用和 WFC 地址可選，優先本次明確欄位，再使用本地號卡已登記地址、同卡最近成功開卡地址；本地無有效地址時由線路目前 WFC 或服務記錄補齊，不按城市或郵編從目錄任選地址。可選姓名、電子郵件、address_two 的空字串按未填處理。", "additionalProperties": false }, "mode": { "type": "string", "enum": [ "sync", "async" ], "description": "async（預設）排隊處理，未完成返回 202；若全部明細在本地校驗時已失敗，可直接返回 200。sync 嘗試立即辦理，整批已有最終結果返回 200，否則返回 202。200 不代表業務成功；均以最終逐卡狀態為準。", "default": "async" }, "webhook_url": { "type": "string", "format": "uri", "description": "可選，本任務的渠道回呼 HTTPS 地址，覆蓋後台登記地址。不要填 API 地址；省略時使用已登記的渠道回呼地址。" } }, "example": { "txid": "channel-reactivation-001", "items": [ { "mdn": "2025550100" } ] }, "additionalProperties": false }, "WifiCallingRequest": { "type": "object", "required": [ "items" ], "properties": { "txid": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]{1,64}$", "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" }, "items": { "type": "array", "items": { "type": "object", "properties": { "esn": { "type": "string", "description": "已分配給本渠道的 ICCID，使用字串保存。", "pattern": "^[0-9]{18,22}$", "minLength": 18, "maxLength": 22 }, "mdn": { "type": "string", "description": "10 位美國手機號碼，不帶 +1、空格或連字符。", "pattern": "^[0-9]{10}$" }, "enrollment_id": { "type": "string", "description": "已登記線路的 Enrollment ID，可單獨用於識別線路；若同時提供 ICCID 或手機號碼，必須指向同一線路。", "minLength": 1, "maxLength": 100 }, "zip": { "type": "string", "pattern": "^\\d{5}$", "description": "五位美國郵政編碼字串，保留前導 0。" }, "feature_action": { "type": "string", "enum": [ "Active" ], "default": "Active" }, "customer": { "type": "object", "properties": { "address": { "type": "string", "description": "真實街道地址。", "minLength": 1, "maxLength": 200 }, "address_two": { "type": "string", "description": "地址補充資訊。", "maxLength": 250 }, "city": { "type": "string", "description": "城市。", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "description": "美國州的兩位字母代碼。", "minLength": 1, "maxLength": 2, "pattern": "^[A-Za-z]{2}$" }, "zip": { "type": "string", "pattern": "^\\d{5}$", "description": "五位美國郵政編碼字串，保留前導 0。", "minLength": 1, "maxLength": 5 } }, "description": "目前明細的客戶資料或地址，覆蓋批次 defaults。", "additionalProperties": false } }, "additionalProperties": false, "anyOf": [ { "required": [ "esn" ] }, { "required": [ "mdn" ] }, { "required": [ "enrollment_id" ] } ] }, "minItems": 1 }, "defaults": { "type": "object", "properties": { "address": { "type": "string", "description": "真實街道地址。", "minLength": 1, "maxLength": 200 }, "address_two": { "type": "string", "description": "地址補充資訊。", "maxLength": 250 }, "city": { "type": "string", "description": "城市。", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "description": "美國州的兩位字母代碼。", "minLength": 1, "maxLength": 2, "pattern": "^[A-Za-z]{2}$" }, "zip": { "type": "string", "pattern": "^\\d{5}$", "description": "五位美國郵政編碼字串，保留前導 0。", "minLength": 1, "maxLength": 5 }, "feature_action": { "type": "string", "enum": [ "Active" ], "default": "Active", "minLength": 1, "maxLength": 250 } }, "description": "批次預設值。啟用必須具備完整真實地址（街道、城市、州、ZIP）；明細 customer、zip 可覆蓋。重新啟用和 WFC 地址可選，優先本次明確欄位，再使用本地號卡已登記地址、同卡最近成功開卡地址；本地無有效地址時由線路目前 WFC 或服務記錄補齊，不按城市或郵編從目錄任選地址。可選姓名、電子郵件、address_two 的空字串按未填處理。", "additionalProperties": false }, "feature_action": { "type": "string", "enum": [ "Active" ], "default": "Active" }, "mode": { "type": "string", "enum": [ "sync", "async" ], "description": "async（預設）排隊處理，未完成返回 202；若全部明細在本地校驗時已失敗，可直接返回 200。sync 嘗試立即辦理，整批已有最終結果返回 200，否則返回 202。200 不代表業務成功；均以最終逐卡狀態為準。", "default": "async" }, "webhook_url": { "type": "string", "format": "uri", "description": "可選，本任務的渠道回呼 HTTPS 地址，覆蓋後台登記地址。不要填 API 地址；省略時使用已登記的渠道回呼地址。" } }, "example": { "txid": "channel-wfc-001", "items": [ { "mdn": "2025550100" } ] }, "additionalProperties": false }, "AddressValidateRequest": { "type": "object", "required": [ "address", "city", "state", "zip" ], "properties": { "address": { "type": "string", "description": "真實街道地址。", "maxLength": 200, "minLength": 1 }, "address_two": { "type": "string", "description": "地址補充資訊。", "maxLength": 200 }, "city": { "type": "string", "description": "城市。", "maxLength": 100, "minLength": 1 }, "state": { "type": "string", "description": "美國州的兩位字母代碼。", "maxLength": 2, "minLength": 1, "pattern": "^[A-Za-z]{2}$" }, "zip": { "type": "string", "pattern": "^\\d{5}$", "description": "五位美國郵政編碼字串，保留前導 0。" }, "enrollment_id": { "type": "string", "description": "可選，已歸屬本渠道的線路 Enrollment ID；用於關聯本次地址校驗，不代替必填地址。", "minLength": 1, "maxLength": 100 } }, "additionalProperties": false }, "RenewalRequest": { "type": "object", "required": [ "items" ], "properties": { "txid": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]{1,64}$", "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" }, "items": { "type": "array", "items": { "type": "object", "properties": { "esn": { "type": "string", "description": "已分配給本渠道的 ICCID，使用字串保存。", "pattern": "^[0-9]{18,22}$", "minLength": 18, "maxLength": 22 }, "mdn": { "type": "string", "description": "10 位美國手機號碼，不帶 +1、空格或連字符。", "pattern": "^[0-9]{10}$" }, "enrollment_id": { "type": "string", "description": "已登記線路的 Enrollment ID，可單獨用於識別線路；若同時提供 ICCID 或手機號碼，必須指向同一線路。", "minLength": 1, "maxLength": 100 } }, "additionalProperties": false, "anyOf": [ { "required": [ "esn" ] }, { "required": [ "mdn" ] }, { "required": [ "enrollment_id" ] } ] }, "minItems": 1 }, "plan_change": { "type": "boolean", "default": false, "description": "false（預設）：續費目前套餐；true：按 plan_id 指定的已開放套餐續費。" }, "plan_id": { "type": "string", "nullable": true, "description": "介面套餐 ID，從目錄讀取。續費換套餐時與 plan_change=true 配合。", "minLength": 1, "maxLength": 100 }, "change_type": { "type": "string", "enum": [ "IMMEDIATE", "ONEXPIRY" ], "description": "IMMEDIATE（預設，可省略）：即日續費，從辦理當日重新開始一個套餐週期，並提供新的資源量。ONEXPIRY：到期續費，保留目前週期，在原到期日追加一個週期。兩種均可現在提交，確認成功後立即記帳；ONEXPIRY 不會等到到期日才發單或扣款。", "default": "IMMEDIATE" }, "mode": { "type": "string", "enum": [ "sync", "async" ], "description": "async（預設）排隊處理，未完成返回 202；若全部明細在本地校驗時已失敗，可直接返回 200。sync 嘗試立即辦理，整批已有最終結果返回 200，否則返回 202。200 不代表業務成功；均以最終逐卡狀態為準。", "default": "async" }, "webhook_url": { "type": "string", "format": "uri", "description": "可選，本任務的渠道回呼 HTTPS 地址，覆蓋後台登記地址。不要填 API 地址；省略時使用已登記的渠道回呼地址。" } }, "example": { "txid": "channel-renewal-001", "change_type": "ONEXPIRY", "items": [ { "mdn": "2025550100" } ] }, "additionalProperties": false }, "Usage": { "type": "object", "properties": { "mdn": { "type": "string", "description": "10 位美國手機號碼，不帶 +1、空格或連字符。" }, "summary": { "type": "boolean" }, "from": { "type": "string", "format": "date", "nullable": true }, "to": { "type": "string", "format": "date", "nullable": true }, "data_used": { "type": "string", "nullable": true }, "data_remaining": { "type": "string", "nullable": true }, "data_limit": { "type": "string", "nullable": true }, "talk_used": { "type": "string", "nullable": true }, "talk_remaining": { "type": "string", "nullable": true }, "text_used": { "type": "string", "nullable": true }, "text_remaining": { "type": "string", "nullable": true }, "records": { "type": "array", "items": { "type": "object" } }, "line_status": { "type": "string", "nullable": true }, "timestamp": { "type": "string", "format": "date-time" } } }, "WebhookItemData": { "type": "object", "required": [ "job_id", "item_id", "status" ], "properties": { "txid": { "type": "string", "nullable": true, "example": "order-99_56789012", "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" }, "job_txid": { "type": "string", "nullable": true, "example": "order-99", "description": "批次的渠道交易號。" }, "job_id": { "type": "string", "example": "ord_example" }, "item_id": { "type": "string", "example": "item_example" }, "esn": { "type": "string", "nullable": true, "description": "已分配給本渠道的 ICCID，使用字串保存。" }, "status": { "type": "string", "enum": [ "succeeded", "failed" ] }, "customer_id": { "type": "string", "nullable": true }, "mdn": { "type": "string", "nullable": true, "description": "10 位美國手機號碼，不帶 +1、空格或連字符。" }, "enrollment_id": { "type": "string", "nullable": true, "description": "已登記線路的 Enrollment ID，可單獨用於識別線路；若同時提供 ICCID 或手機號碼，必須指向同一線路。" }, "error": { "type": "string" }, "error_code": { "type": "string", "description": "穩定的業務錯誤碼。" }, "retryable": { "type": "boolean", "description": "true 僅表示允許主動重試，不代表自動重試。明確 failed 的明細返回失敗結果、不扣款，並進入異常待解決；核實後再決定是否手動重試。" }, "details": {} }, "additionalProperties": true }, "WebhookJobData": { "type": "object", "required": [ "job_id", "status", "total", "succeeded", "failed" ], "properties": { "txid": { "type": "string", "nullable": true, "example": "order-99", "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" }, "job_txid": { "type": "string", "nullable": true, "example": "order-99", "description": "批次的渠道交易號。" }, "job_id": { "type": "string", "example": "ord_example" }, "status": { "type": "string", "enum": [ "succeeded", "failed", "partial" ] }, "total": { "type": "integer", "example": 2 }, "succeeded": { "type": "integer", "example": 1 }, "failed": { "type": "integer", "example": 1 }, "pending": { "type": "integer", "minimum": 0, "example": 0 } } }, "WebhookItemEvent": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "example": "evt_01hxyz" }, "type": { "type": "string", "enum": [ "activation.item.succeeded", "activation.item.failed", "renewal.item.succeeded", "renewal.item.failed", "reactivation.item.succeeded", "reactivation.item.failed", "wifi_calling.item.succeeded", "wifi_calling.item.failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/WebhookItemData" } } }, "WebhookJobEvent": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "example": "evt_01hjob" }, "type": { "type": "string", "enum": [ "activation.job.completed", "renewal.job.completed", "reactivation.job.completed", "wifi_calling.job.completed" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/WebhookJobData" } } }, "WebhookEvent": { "oneOf": [ { "$ref": "#/components/schemas/WebhookItemEvent" }, { "$ref": "#/components/schemas/WebhookJobEvent" } ] }, "ExtensionPagination": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "page", "per_page", "total", "has_more" ] }, "ExtensionWallet": { "type": "object", "properties": { "balance": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "15.00", "description": "USD，兩位小數字串" }, "available": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "15.00", "description": "USD，兩位小數字串" }, "currency": { "type": "string", "enum": [ "USD" ] } }, "required": [ "balance", "available", "currency" ] }, "ExtensionLedgerEntry": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "recharge", "debit" ] }, "reference": { "type": "string" }, "change": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "15.00", "description": "本次變動，儲值為正數、消耗為負數" }, "balance_after": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "15.00", "description": "USD，兩位小數字串" }, "order_id": { "type": "string", "nullable": true }, "item_id": { "type": "string", "nullable": true }, "txid": { "type": "string", "nullable": true }, "iccid": { "type": "string", "nullable": true }, "operation": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string", "enum": [ "USD" ] } }, "required": [ "id", "kind", "reference", "change", "balance_after", "order_id", "item_id", "txid", "iccid", "operation", "created_at", "currency" ] }, "ExtensionLedgerSummary": { "type": "object", "properties": { "total": { "type": "integer" }, "recharge_count": { "type": "integer" }, "consumption_count": { "type": "integer" }, "opening_balance": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "15.00", "description": "USD，兩位小數字串" }, "recharge": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "15.00", "description": "USD，兩位小數字串" }, "consumption": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "15.00", "description": "USD，兩位小數字串" }, "closing_balance": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "15.00", "description": "USD，兩位小數字串" }, "current_balance": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "15.00", "description": "USD，兩位小數字串" }, "currency": { "type": "string", "enum": [ "USD" ] }, "timezone": { "type": "string", "enum": [ "America/New_York" ] } }, "required": [ "total", "recharge_count", "consumption_count", "opening_balance", "recharge", "consumption", "closing_balance", "current_balance", "currency", "timezone" ] }, "ExtensionCard": { "type": "object", "properties": { "iccid": { "type": "string" }, "sim_type": { "type": "string", "enum": [ "physical", "esim" ] }, "status": { "type": "string", "enum": [ "free", "active", "inactive" ] }, "mdn": { "type": "string", "nullable": true }, "plan_code": { "type": "string", "nullable": true }, "scheduled_plan_code": { "type": "string", "nullable": true }, "upstream_line_status": { "type": "string", "nullable": true }, "last_synced_at": { "type": "string", "nullable": true }, "service_address": { "type": "object", "nullable": true }, "catalog_entry_id": { "type": "string", "nullable": true }, "catalog_snapshot": { "type": "object", "nullable": true } }, "required": [ "iccid", "sim_type", "status", "mdn", "plan_code", "scheduled_plan_code", "upstream_line_status", "last_synced_at", "service_address", "catalog_entry_id", "catalog_snapshot" ] }, "ExtensionServiceAddress": { "type": "object", "properties": { "address": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "maxLength": 100 }, "state": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "zip": { "type": "string", "pattern": "^\\d{5}$" } }, "required": [ "address", "city", "state", "zip" ] }, "ExtensionZipRegion": { "type": "object", "properties": { "zip": { "type": "string", "pattern": "^\\d{5}$" }, "city": { "type": "string" }, "state": { "type": "string", "pattern": "^[A-Z]{2}$" }, "state_name": { "type": "string" }, "city_source": { "type": "string", "enum": [ "activation_history", "address_reference", "verified_reference" ] }, "reference_cities": { "type": "array", "items": { "type": "string" } }, "location_note": { "type": "string" }, "area_codes": { "type": "array", "items": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "readOnly": true, "description": "通用展示及區號篩選欄位：合併同城市同州的歷史區號和已確認實開區號；兩類記錄均為空才回退地區參考。僅展示已確認實開區號時使用 city_issued_area_codes。" }, "area_code_source": { "type": "string", "enum": [ "city_activation_history", "geographic_reference", "none" ], "readOnly": true }, "city_issued_area_codes": { "type": "array", "items": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "readOnly": true, "description": "渠道下拉列表專用：同城市同州已確認的實開區號，不分套餐。按核實過的開卡記錄歸集，不混入未核實歷史或地理參考；無記錄為 []。並非實時庫存，不能保證或指定區號。" }, "city_issued_area_code_samples": { "type": "array", "items": { "type": "object", "properties": { "area_code": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "sample_count": { "type": "integer", "minimum": 1 } }, "required": [ "area_code", "sample_count" ] }, "readOnly": true, "description": "城市各已確認實開區號的去重號碼數量，報告與 API 同號碼去重" }, "city_issued_sample_count": { "type": "integer", "minimum": 0, "readOnly": true, "description": "城市已確認實開記錄的去重號碼數；同城多條回應重複返回，不可相加；與舊歷史樣本可重疊" }, "city_issued_history_zips": { "type": "array", "items": { "type": "string", "pattern": "^\\d{5}$" }, "readOnly": true, "description": "同城含已確認實開記錄的郵編" }, "city_issued_last_observed_on": { "type": "string", "format": "date", "nullable": true, "readOnly": true, "description": "城市已知的最近實開日期；缺少日期或記錄為 null" }, "city_issued_sources": { "type": "array", "items": { "type": "string", "enum": [ "rogue_activation_report", "rogue_api" ] }, "readOnly": true, "description": "記錄類別標識，僅用於資料追蹤；無記錄為 []，介面區號選擇使用 city_issued_area_codes" }, "issued_sample_count": { "type": "integer", "minimum": 0, "readOnly": true, "description": "本 ZIP 已確認實開記錄的去重號碼數" }, "issued_last_observed_on": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "city_historical_area_codes": { "type": "array", "items": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "readOnly": true, "description": "同城市、同州全部郵編原導入歷史樣本的區號，不分套餐。保留舊統計，來源可能混合；不代表全部記錄均已核實" }, "city_area_code_samples": { "type": "array", "items": { "type": "object", "properties": { "area_code": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "sample_count": { "type": "integer", "minimum": 1 } }, "required": [ "area_code", "sample_count" ] }, "readOnly": true }, "city_sample_count": { "type": "integer", "minimum": 0, "readOnly": true, "description": "城市全部郵編樣本匯總，同城回應中重複返回，不可跨郵編相加" }, "city_history_zips": { "type": "array", "items": { "type": "string", "pattern": "^\\d{5}$" }, "readOnly": true, "description": "同城有歷史樣本的郵編" }, "city_last_observed_on": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "historical_area_codes": { "type": "array", "items": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "readOnly": true }, "area_code_samples": { "type": "array", "items": { "type": "object", "properties": { "area_code": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "sample_count": { "type": "integer", "minimum": 1 } }, "required": [ "area_code", "sample_count" ] } }, "reference_area_codes": { "type": "array", "items": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "readOnly": true, "description": "獨立保留的地理核驗資料。展示及篩選使用area_codes，本欄位不覆蓋城市實開區號；空陣列表示尚未補充" }, "reference_sources": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "title", "url" ] }, "readOnly": true }, "reference_checked_on": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "reference_scope": { "type": "string", "nullable": true, "readOnly": true }, "sample_count": { "type": "integer", "minimum": 0 }, "history_status": { "type": "string", "enum": [ "observed", "no_samples" ] }, "last_observed_on": { "type": "string", "format": "date", "nullable": true }, "area_code_guaranteed": { "type": "boolean", "enum": [ false ], "readOnly": true }, "notice": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "zip", "city", "state", "state_name", "city_source", "reference_cities", "location_note", "area_codes", "area_code_source", "city_issued_area_codes", "city_issued_area_code_samples", "city_issued_sample_count", "city_issued_history_zips", "city_issued_last_observed_on", "city_issued_sources", "issued_sample_count", "issued_last_observed_on", "city_historical_area_codes", "city_area_code_samples", "city_sample_count", "city_history_zips", "city_last_observed_on", "historical_area_codes", "area_code_samples", "reference_area_codes", "reference_sources", "reference_checked_on", "reference_scope", "sample_count", "history_status", "last_observed_on", "area_code_guaranteed", "notice", "updated_at" ] }, "ExtensionRegionalCatalog": { "type": "object", "properties": { "id": { "type": "string" }, "revision": { "type": "string" }, "plan_code": { "type": "string", "nullable": true }, "plan_name": { "type": "string" }, "service_address": { "$ref": "#/components/schemas/ExtensionServiceAddress" }, "zip_region": { "type": "object", "properties": { "zip": { "type": "string", "pattern": "^\\d{5}$" }, "city": { "type": "string" }, "state": { "type": "string", "pattern": "^[A-Z]{2}$" }, "state_name": { "type": "string" }, "city_source": { "type": "string", "enum": [ "activation_history", "address_reference", "verified_reference" ] }, "reference_cities": { "type": "array", "items": { "type": "string" } }, "location_note": { "type": "string" }, "area_codes": { "type": "array", "items": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "readOnly": true, "description": "通用展示及區號篩選欄位：合併同城市同州的歷史區號和已確認實開區號；兩類記錄均為空才回退地區參考。僅展示已確認實開區號時使用 city_issued_area_codes。" }, "area_code_source": { "type": "string", "enum": [ "city_activation_history", "geographic_reference", "none" ], "readOnly": true }, "city_issued_area_codes": { "type": "array", "items": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "readOnly": true, "description": "渠道下拉列表專用：同城市同州已確認的實開區號，不分套餐。按核實過的開卡記錄歸集，不混入未核實歷史或地理參考；無記錄為 []。並非實時庫存，不能保證或指定區號。" }, "city_issued_area_code_samples": { "type": "array", "items": { "type": "object", "properties": { "area_code": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "sample_count": { "type": "integer", "minimum": 1 } }, "required": [ "area_code", "sample_count" ] }, "readOnly": true, "description": "城市各已確認實開區號的去重號碼數量，報告與 API 同號碼去重" }, "city_issued_sample_count": { "type": "integer", "minimum": 0, "readOnly": true, "description": "城市已確認實開記錄的去重號碼數；同城多條回應重複返回，不可相加；與舊歷史樣本可重疊" }, "city_issued_history_zips": { "type": "array", "items": { "type": "string", "pattern": "^\\d{5}$" }, "readOnly": true, "description": "同城含已確認實開記錄的郵編" }, "city_issued_last_observed_on": { "type": "string", "format": "date", "nullable": true, "readOnly": true, "description": "城市已知的最近實開日期；缺少日期或記錄為 null" }, "city_issued_sources": { "type": "array", "items": { "type": "string", "enum": [ "rogue_activation_report", "rogue_api" ] }, "readOnly": true, "description": "記錄類別標識，僅用於資料追蹤；無記錄為 []，介面區號選擇使用 city_issued_area_codes" }, "issued_sample_count": { "type": "integer", "minimum": 0, "readOnly": true, "description": "本 ZIP 已確認實開記錄的去重號碼數" }, "issued_last_observed_on": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "city_historical_area_codes": { "type": "array", "items": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "readOnly": true, "description": "同城市、同州全部郵編原導入歷史樣本的區號，不分套餐。保留舊統計，來源可能混合；不代表全部記錄均已核實" }, "city_area_code_samples": { "type": "array", "items": { "type": "object", "properties": { "area_code": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "sample_count": { "type": "integer", "minimum": 1 } }, "required": [ "area_code", "sample_count" ] }, "readOnly": true }, "city_sample_count": { "type": "integer", "minimum": 0, "readOnly": true, "description": "城市全部郵編樣本匯總，同城回應中重複返回，不可跨郵編相加" }, "city_history_zips": { "type": "array", "items": { "type": "string", "pattern": "^\\d{5}$" }, "readOnly": true, "description": "同城有歷史樣本的郵編" }, "city_last_observed_on": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "historical_area_codes": { "type": "array", "items": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "readOnly": true }, "area_code_samples": { "type": "array", "items": { "type": "object", "properties": { "area_code": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "sample_count": { "type": "integer", "minimum": 1 } }, "required": [ "area_code", "sample_count" ] } }, "reference_area_codes": { "type": "array", "items": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" }, "readOnly": true, "description": "獨立保留的地理核驗資料。展示及篩選使用area_codes，本欄位不覆蓋城市實開區號；空陣列表示尚未補充" }, "reference_sources": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "title", "url" ] }, "readOnly": true }, "reference_checked_on": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "reference_scope": { "type": "string", "nullable": true, "readOnly": true }, "sample_count": { "type": "integer", "minimum": 0 }, "history_status": { "type": "string", "enum": [ "observed", "no_samples" ] }, "last_observed_on": { "type": "string", "format": "date", "nullable": true }, "area_code_guaranteed": { "type": "boolean", "enum": [ false ], "readOnly": true }, "notice": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "zip", "city", "state", "state_name", "city_source", "reference_cities", "location_note", "area_codes", "area_code_source", "city_issued_area_codes", "city_issued_area_code_samples", "city_issued_sample_count", "city_issued_history_zips", "city_issued_last_observed_on", "city_issued_sources", "issued_sample_count", "issued_last_observed_on", "city_historical_area_codes", "city_area_code_samples", "city_sample_count", "city_history_zips", "city_last_observed_on", "historical_area_codes", "area_code_samples", "reference_area_codes", "reference_sources", "reference_checked_on", "reference_scope", "sample_count", "history_status", "last_observed_on", "area_code_guaranteed", "notice", "updated_at" ], "nullable": true, "readOnly": true, "description": "按ZIP關聯的只讀參考資料；未導入時為null。更新此資料不改變目錄id或revision。" }, "verification_status": { "type": "string", "enum": [ "matched", "updated", "supplemented", "not_found", "query_failed", "ambiguous", "retired" ] }, "available": { "type": "boolean" }, "orderable": { "type": "boolean" }, "currency": { "type": "string", "enum": [ "USD" ] }, "prices": { "type": "object", "properties": { "activate_physical": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "15.00", "description": "USD，兩位小數字串", "nullable": true }, "activate_esim": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "15.00", "description": "USD，兩位小數字串", "nullable": true }, "renew": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "15.00", "description": "USD，兩位小數字串", "nullable": true }, "reactivate": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "15.00", "description": "USD，兩位小數字串", "nullable": true }, "plan_change": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "example": "15.00", "description": "USD，兩位小數字串", "nullable": true } }, "required": [ "activate_physical", "activate_esim", "renew", "reactivate", "plan_change" ] }, "unavailable_reason": { "type": "string", "nullable": true }, "checked_at": { "type": "string", "nullable": true }, "product_code": { "type": "string", "nullable": true }, "plan_id": { "type": "string", "nullable": true }, "catalog_entry_id": { "type": "string", "description": "唯一地區套餐目錄 ID，可直接用於開卡。" } }, "required": [ "id", "revision", "plan_code", "plan_name", "service_address", "zip_region", "verification_status", "available", "orderable", "currency", "prices", "unavailable_reason", "checked_at", "product_code", "plan_id", "catalog_entry_id" ] } } }, "paths": { "/status": { "get": { "tags": [ "查詢" ], "summary": "服務狀態", "security": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ServiceStatus" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "description": "查詢完成", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "get__status", "description": "檢查平台入口是否運行，不代表每個業務請求都會成功。" } }, "/auth": { "post": { "tags": [ "相容接入" ], "summary": "取得存取權杖（可選相容）", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "partner_id", "api_key" ], "properties": { "partner_id": { "type": "string", "example": "your_partner_id", "description": "平台分配的渠道代碼。", "minLength": 1, "maxLength": 32 }, "api_key": { "type": "string", "description": "平台發放的固定 API Key；日常請求放在 X-API-Key 標頭，無需換取權杖。", "minLength": 1, "maxLength": 120 } }, "additionalProperties": false } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Token" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "description": "已簽發存取權杖", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "413": { "description": "請求內容過大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求內容過大", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "415": { "description": "需要 JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "需要 JSON", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "post__auth", "description": "僅供已使用臨時 token 的接入繼續相容；新接入直接使用帳戶和固定 Key，不需要呼叫此介面。相容 token 有效期 30 分鐘，使用 `Authorization: Bearer `，不要與固定 Key 標頭同時發送。此介面每 IP 每分鐘最多 20 次。" } }, "/plans": { "get": { "tags": [ "套餐" ], "summary": "按郵編查詢可售套餐", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "zip", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{5}$" }, "description": "五位美國郵政編碼字串，保留前導 0。" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "description": "查詢完成", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "參數錯誤", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "查詢服務異常；收費請求結果不明時先查原交易號", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "查詢服務異常；收費請求結果不明時先查原交易號", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "get__plans" } }, "/customers": { "get": { "tags": [ "查詢" ], "summary": "按 ICCID、手機號碼或 Enrollment ID 查詢線路", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "mdn", "in": "query", "schema": { "type": "string", "pattern": "^\\d{10}$" }, "description": "10 位美國手機號碼，不帶 +1、空格或連字符。" }, { "name": "esn", "in": "query", "schema": { "type": "string" }, "description": "已分配給本渠道的 ICCID，使用字串保存。" }, { "name": "enrollment_id", "in": "query", "schema": { "type": "string" }, "description": "已登記線路的 Enrollment ID；本查詢只能從 enrollment_id、esn、mdn 中選擇一個標識，不可同時傳入。" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomerLine" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "description": "查詢完成", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "參數錯誤", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "未找到本渠道的資料", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "線路標識對應多張卡，請核實渠道內歸屬記錄", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "線路標識對應多張卡，請核實渠道內歸屬記錄", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "查詢服務異常；收費請求結果不明時先查原交易號", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "查詢服務異常；收費請求結果不明時先查原交易號", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "get__customers", "description": "esn、mdn、enrollment_id 必須且只能提供一個查詢鍵，並且線路必須已歸屬本渠道。" } }, "/addresses/validate": { "post": { "tags": [ "查詢" ], "summary": "校驗服務地址及 Wi-Fi Calling 地址資格", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidateRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "valid": { "type": "boolean" }, "address": { "type": "object", "properties": { "address": { "type": "string", "description": "真實街道地址。" }, "address_two": { "type": "string", "description": "地址補充資訊。" }, "city": { "type": "string", "description": "城市。" }, "state": { "type": "string", "description": "美國州的兩位字母代碼。" }, "zip": { "type": "string", "description": "五位美國郵政編碼字串，保留前導 0。" } }, "description": "地址校驗返回的地址物件，包含街道、城市、州和 ZIP 等欄位。" } } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "description": "查詢完成", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "參數錯誤", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "未找到本渠道的資料", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "線路標識對應多張卡，請核實渠道內歸屬記錄", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "線路標識對應多張卡，請核實渠道內歸屬記錄", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "413": { "description": "請求內容過大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求內容過大", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "415": { "description": "需要 JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "需要 JSON", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "查詢服務異常；收費請求結果不明時先查原交易號", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "查詢服務異常；收費請求結果不明時先查原交易號", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "post__addresses_validate", "description": "只校驗地址與 Wi-Fi Calling 地址資格，不會開啟 Wi-Fi Calling。" } }, "/mdns/{mdn}": { "get": { "tags": [ "查詢" ], "summary": "按手機號碼查詢線路", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "mdn", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{10}$" }, "description": "10 位美國手機號碼，不帶 +1、空格或連字符。" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomerLine" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "description": "查詢完成", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "參數錯誤", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "未找到本渠道的資料", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "線路標識對應多張卡，請核實渠道內歸屬記錄", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "線路標識對應多張卡，請核實渠道內歸屬記錄", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "查詢服務異常；收費請求結果不明時先查原交易號", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "查詢服務異常；收費請求結果不明時先查原交易號", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "get__mdns_mdn_" } }, "/mdns/{mdn}/usage": { "get": { "tags": [ "查詢" ], "summary": "查詢用量", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "mdn", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{10}$" }, "description": "10 位美國手機號碼，不帶 +1、空格或連字符。" }, { "name": "summary", "in": "query", "schema": { "type": "boolean" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Usage" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "description": "查詢完成", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "參數錯誤", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "未找到本渠道的資料", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "線路標識對應多張卡，請核實渠道內歸屬記錄", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "線路標識對應多張卡，請核實渠道內歸屬記錄", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "查詢服務異常；收費請求結果不明時先查原交易號", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "查詢服務異常；收費請求結果不明時先查原交易號", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "get__mdns_mdn_usage", "description": "查詢最近 90 天用量，預設 summary=true。按日查詢時同時提供 from、to，不能與 summary=true 同用。缺失欄位或 null 不代表零用量。" } }, "/esns/{esn}/status": { "get": { "tags": [ "查詢" ], "summary": "查詢 SIM 狀態", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "esn", "in": "path", "required": true, "schema": { "type": "string" }, "description": "已分配給本渠道的 ICCID，使用字串保存。" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InventoryStatus" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "description": "查詢完成", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "未找到本渠道的資料", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "查詢服務異常；收費請求結果不明時先查原交易號", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "查詢服務異常；收費請求結果不明時先查原交易號", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "get__esns_esn_status" } }, "/jobs/activations": { "post": { "tags": [ "業務辦理" ], "summary": "提交開卡", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "僅在請求體未傳 txid 時使用；優先使用 JSON txid。" }, { "name": "txid", "in": "header", "required": false, "schema": { "type": "string" }, "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivationRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "example": { "data": { "job": { "id": "ord_example", "txid": "channel-activation-001", "partner_id": "your_channel", "type": "activation", "status": "succeeded", "totals": { "total": 1, "succeeded": 1, "failed": 0, "pending": 0 }, "billing": { "amount": "2.60", "charged_amount": "2.60", "currency": "USD" } }, "items": [ { "id": "item_example", "job_id": "ord_example", "job_txid": "channel-activation-001", "txid": "channel-activation-001", "esn": "89000000000000000001", "status": "succeeded", "result": { "mdn": "2025550100", "retryable": false }, "billing": { "price": "2.60", "charged_amount": "2.60", "currency": "USD" } } ] }, "meta": { "request_id": "req_example", "job_id": "ord_example", "txid": "channel-activation-001" } } } }, "description": "請求完成；業務結果以逐卡狀態為準", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "example": { "data": { "job": { "id": "ord_example", "txid": "channel-activation-001", "partner_id": "your_channel", "type": "activation", "status": "queued", "totals": { "total": 1, "succeeded": 0, "failed": 0, "pending": 1 }, "billing": { "amount": "2.60", "charged_amount": "0.00", "currency": "USD" } }, "items": [ { "id": "item_example", "job_id": "ord_example", "job_txid": "channel-activation-001", "txid": "channel-activation-001", "esn": "89000000000000000001", "status": "pending", "result": null, "billing": { "price": "2.60", "charged_amount": "0.00", "currency": "USD" } } ] }, "meta": { "request_id": "req_example", "job_id": "ord_example", "txid": "channel-activation-001" } } } }, "description": "任務已受理，等待最終結果", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "參數錯誤", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "402": { "description": "餘額不足，未提交", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_balance", "message": "餘額不足，未提交", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "未找到本渠道的資料", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "交易號衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "交易號衝突或狀態衝突", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "413": { "description": "請求內容過大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求內容過大", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "415": { "description": "需要 JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "需要 JSON", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "查詢服務異常；收費請求結果不明時先查原交易號", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "查詢服務異常；收費請求結果不明時先查原交易號", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "post__jobs_activations", "description": "校驗歸屬與可辦理明細的總報價、餘額後受理；逐卡業務錯誤只影響該卡，其餘明細繼續同批辦理。同一 txid 重複返回 409，請查詢原任務。整批已有最終結果返回 200（包括全部明細本地校驗失敗）；排隊或結果待確認返回 202。200 不代表業務成功，須檢查逐卡狀態。已驗簽並關聯目前辦理的逐卡最終回呼直接更新結果；未確認結果缺失、不完整或衝突時補查原批次，不重複辦理。已確認終態後收到相反結果，保留結算並記錄異常待核實。", "callbacks": { "businessResult": { "{$request.body#/webhook_url}": { "post": { "summary": "接收業務事件（由平台發送）", "security": [], "description": "回呼使用獨立 Webhook Secret 驗簽，不發送渠道帳戶或 API Key。對原始請求體計算 HMAC-SHA256，不拼接時間戳；created_at 為事件建立時間。平台在事件落庫後立即觸發投遞，待發通知連續發送，不設每秒或每輪固定條數限制；實際投遞時間取決於接收方與網路。首次投遞失敗後，平台最多自動重試 5 次，間隔為 30、60、120、240、480 秒，指數退避上限為 15 分鐘，包括首次在內最多投遞 6 次。平台重投原事件，不重新辦理業務或扣款。", "parameters": [ { "name": "X-RM-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "activation.item.succeeded", "activation.item.failed", "activation.job.completed" ] }, "description": "與 JSON type 一致。" }, { "name": "X-RM-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string", "example": "delivery_example" }, "description": "本次投遞嘗試編號，重投時改變；使用 JSON id 作為穩定事件去重鍵。" }, { "name": "X-RM-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[a-f0-9]{64}$" }, "description": "sha256= 加原始請求體的 HMAC-SHA256 十六進制簽名；密鑰為渠道 Webhook Secret。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "已驗簽、持久化並去重" } } } } } } } }, "/jobs/reactivations": { "post": { "tags": [ "業務辦理" ], "summary": "提交重新啟用", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "僅在請求體未傳 txid 時使用；優先使用 JSON txid。" }, { "name": "txid", "in": "header", "required": false, "schema": { "type": "string" }, "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReactivationRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "example": { "data": { "job": { "id": "ord_example", "txid": "channel-reactivation-001", "partner_id": "your_channel", "type": "reactivation", "status": "succeeded", "totals": { "total": 1, "succeeded": 1, "failed": 0, "pending": 0 }, "billing": { "amount": "2.60", "charged_amount": "2.60", "currency": "USD" } }, "items": [ { "id": "item_example", "job_id": "ord_example", "job_txid": "channel-reactivation-001", "txid": "channel-reactivation-001", "esn": "89000000000000000001", "status": "succeeded", "result": { "mdn": "2025550100", "retryable": false }, "billing": { "price": "2.60", "charged_amount": "2.60", "currency": "USD" } } ] }, "meta": { "request_id": "req_example", "job_id": "ord_example", "txid": "channel-reactivation-001" } } } }, "description": "請求完成；業務結果以逐卡狀態為準", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "example": { "data": { "job": { "id": "ord_example", "txid": "channel-reactivation-001", "partner_id": "your_channel", "type": "reactivation", "status": "queued", "totals": { "total": 1, "succeeded": 0, "failed": 0, "pending": 1 }, "billing": { "amount": "2.60", "charged_amount": "0.00", "currency": "USD" } }, "items": [ { "id": "item_example", "job_id": "ord_example", "job_txid": "channel-reactivation-001", "txid": "channel-reactivation-001", "esn": "89000000000000000001", "status": "pending", "result": null, "billing": { "price": "2.60", "charged_amount": "0.00", "currency": "USD" } } ] }, "meta": { "request_id": "req_example", "job_id": "ord_example", "txid": "channel-reactivation-001" } } } }, "description": "任務已受理，等待最終結果", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "參數錯誤", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "402": { "description": "餘額不足，未提交", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_balance", "message": "餘額不足，未提交", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "未找到本渠道的資料", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "交易號衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "交易號衝突或狀態衝突", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "413": { "description": "請求內容過大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求內容過大", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "415": { "description": "需要 JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "需要 JSON", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "查詢服務異常；收費請求結果不明時先查原交易號", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "查詢服務異常；收費請求結果不明時先查原交易號", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "post__jobs_reactivations", "description": "校驗歸屬與可辦理明細的總報價、餘額後受理；逐卡業務錯誤只影響該卡，其餘明細繼續同批辦理。同一 txid 重複返回 409，請查詢原任務。整批已有最終結果返回 200（包括全部明細本地校驗失敗）；排隊或結果待確認返回 202。200 不代表業務成功，須檢查逐卡狀態。已驗簽並關聯目前辦理的逐卡最終回呼直接更新結果；未確認結果缺失、不完整或衝突時補查原批次，不重複辦理。已確認終態後收到相反結果，保留結算並記錄異常待核實。", "callbacks": { "businessResult": { "{$request.body#/webhook_url}": { "post": { "summary": "接收業務事件（由平台發送）", "security": [], "description": "回呼使用獨立 Webhook Secret 驗簽，不發送渠道帳戶或 API Key。對原始請求體計算 HMAC-SHA256，不拼接時間戳；created_at 為事件建立時間。平台在事件落庫後立即觸發投遞，待發通知連續發送，不設每秒或每輪固定條數限制；實際投遞時間取決於接收方與網路。首次投遞失敗後，平台最多自動重試 5 次，間隔為 30、60、120、240、480 秒，指數退避上限為 15 分鐘，包括首次在內最多投遞 6 次。平台重投原事件，不重新辦理業務或扣款。", "parameters": [ { "name": "X-RM-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "reactivation.item.succeeded", "reactivation.item.failed", "reactivation.job.completed" ] }, "description": "與 JSON type 一致。" }, { "name": "X-RM-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string", "example": "delivery_example" }, "description": "本次投遞嘗試編號，重投時改變；使用 JSON id 作為穩定事件去重鍵。" }, { "name": "X-RM-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[a-f0-9]{64}$" }, "description": "sha256= 加原始請求體的 HMAC-SHA256 十六進制簽名；密鑰為渠道 Webhook Secret。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "已驗簽、持久化並去重" } } } } } } } }, "/jobs/renewals": { "post": { "tags": [ "業務辦理" ], "summary": "提交續費", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "僅在請求體未傳 txid 時使用；優先使用 JSON txid。" }, { "name": "txid", "in": "header", "required": false, "schema": { "type": "string" }, "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewalRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "example": { "data": { "job": { "id": "ord_example", "txid": "channel-renewal-001", "partner_id": "your_channel", "type": "renewal", "status": "succeeded", "totals": { "total": 1, "succeeded": 1, "failed": 0, "pending": 0 }, "billing": { "amount": "2.60", "charged_amount": "2.60", "currency": "USD" } }, "items": [ { "id": "item_example", "job_id": "ord_example", "job_txid": "channel-renewal-001", "txid": "channel-renewal-001", "esn": "89000000000000000001", "status": "succeeded", "result": { "mdn": "2025550100", "retryable": false }, "billing": { "price": "2.60", "charged_amount": "2.60", "currency": "USD" } } ] }, "meta": { "request_id": "req_example", "job_id": "ord_example", "txid": "channel-renewal-001" } } } }, "description": "請求完成；業務結果以逐卡狀態為準", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "example": { "data": { "job": { "id": "ord_example", "txid": "channel-renewal-001", "partner_id": "your_channel", "type": "renewal", "status": "queued", "totals": { "total": 1, "succeeded": 0, "failed": 0, "pending": 1 }, "billing": { "amount": "2.60", "charged_amount": "0.00", "currency": "USD" } }, "items": [ { "id": "item_example", "job_id": "ord_example", "job_txid": "channel-renewal-001", "txid": "channel-renewal-001", "esn": "89000000000000000001", "status": "pending", "result": null, "billing": { "price": "2.60", "charged_amount": "0.00", "currency": "USD" } } ] }, "meta": { "request_id": "req_example", "job_id": "ord_example", "txid": "channel-renewal-001" } } } }, "description": "任務已受理，等待最終結果", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "參數錯誤", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "402": { "description": "餘額不足，未提交", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_balance", "message": "餘額不足，未提交", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "未找到本渠道的資料", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "交易號衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "交易號衝突或狀態衝突", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "413": { "description": "請求內容過大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求內容過大", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "415": { "description": "需要 JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "需要 JSON", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "查詢服務異常；收費請求結果不明時先查原交易號", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "查詢服務異常；收費請求結果不明時先查原交易號", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "post__jobs_renewals", "description": "校驗歸屬與可辦理明細的總報價、餘額後受理；逐卡業務錯誤只影響該卡，其餘明細繼續同批辦理。同一 txid 重複返回 409，請查詢原任務。整批已有最終結果返回 200（包括全部明細本地校驗失敗）；排隊或結果待確認返回 202。200 不代表業務成功，須檢查逐卡狀態。已驗簽並關聯目前辦理的逐卡最終回呼直接更新結果；未確認結果缺失、不完整或衝突時補查原批次，不重複辦理。已確認終態後收到相反結果，保留結算並記錄異常待核實。", "callbacks": { "businessResult": { "{$request.body#/webhook_url}": { "post": { "summary": "接收業務事件（由平台發送）", "security": [], "description": "回呼使用獨立 Webhook Secret 驗簽，不發送渠道帳戶或 API Key。對原始請求體計算 HMAC-SHA256，不拼接時間戳；created_at 為事件建立時間。平台在事件落庫後立即觸發投遞，待發通知連續發送，不設每秒或每輪固定條數限制；實際投遞時間取決於接收方與網路。首次投遞失敗後，平台最多自動重試 5 次，間隔為 30、60、120、240、480 秒，指數退避上限為 15 分鐘，包括首次在內最多投遞 6 次。平台重投原事件，不重新辦理業務或扣款。", "parameters": [ { "name": "X-RM-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "renewal.item.succeeded", "renewal.item.failed", "renewal.job.completed" ] }, "description": "與 JSON type 一致。" }, { "name": "X-RM-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string", "example": "delivery_example" }, "description": "本次投遞嘗試編號，重投時改變；使用 JSON id 作為穩定事件去重鍵。" }, { "name": "X-RM-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[a-f0-9]{64}$" }, "description": "sha256= 加原始請求體的 HMAC-SHA256 十六進制簽名；密鑰為渠道 Webhook Secret。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "已驗簽、持久化並去重" } } } } } } } }, "/jobs/wifi-calling": { "post": { "tags": [ "業務辦理" ], "summary": "免費開啟 Wi-Fi Calling", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "僅在請求體未傳 txid 時使用；優先使用 JSON txid。" }, { "name": "txid", "in": "header", "required": false, "schema": { "type": "string" }, "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WifiCallingRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "example": { "data": { "job": { "id": "ord_example", "txid": "channel-wfc-001", "partner_id": "your_channel", "type": "wifi_calling", "status": "succeeded", "totals": { "total": 1, "succeeded": 1, "failed": 0, "pending": 0 }, "billing": { "amount": "0.00", "charged_amount": "0.00", "currency": "USD" } }, "items": [ { "id": "item_example", "job_id": "ord_example", "job_txid": "channel-wfc-001", "txid": "channel-wfc-001", "esn": "89000000000000000001", "status": "succeeded", "result": { "mdn": "2025550100", "retryable": false }, "billing": { "price": "0.00", "charged_amount": "0.00", "currency": "USD" } } ] }, "meta": { "request_id": "req_example", "job_id": "ord_example", "txid": "channel-wfc-001" } } } }, "description": "請求完成；業務結果以逐卡狀態為準", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "example": { "data": { "job": { "id": "ord_example", "txid": "channel-wfc-001", "partner_id": "your_channel", "type": "wifi_calling", "status": "queued", "totals": { "total": 1, "succeeded": 0, "failed": 0, "pending": 1 }, "billing": { "amount": "0.00", "charged_amount": "0.00", "currency": "USD" } }, "items": [ { "id": "item_example", "job_id": "ord_example", "job_txid": "channel-wfc-001", "txid": "channel-wfc-001", "esn": "89000000000000000001", "status": "pending", "result": null, "billing": { "price": "0.00", "charged_amount": "0.00", "currency": "USD" } } ] }, "meta": { "request_id": "req_example", "job_id": "ord_example", "txid": "channel-wfc-001" } } } }, "description": "任務已受理，等待最終結果", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "參數錯誤", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "未找到本渠道的資料", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "交易號衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "交易號衝突或狀態衝突", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "413": { "description": "請求內容過大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求內容過大", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "415": { "description": "需要 JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "需要 JSON", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "查詢服務異常；收費請求結果不明時先查原交易號", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "查詢服務異常；收費請求結果不明時先查原交易號", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "post__jobs_wifi_calling", "description": "獨立開啟 WFC，僅支援 Active，不單獨收費，不扣渠道餘額。地址可省略，優先本次明確欄位、本地號卡已登記地址、同卡最近成功開卡地址；本地無有效地址時使用線路目前 WFC 或服務記錄。結果透過任務和回呼返回。", "callbacks": { "businessResult": { "{$request.body#/webhook_url}": { "post": { "summary": "接收業務事件（由平台發送）", "security": [], "description": "回呼使用獨立 Webhook Secret 驗簽，不發送渠道帳戶或 API Key。對原始請求體計算 HMAC-SHA256，不拼接時間戳；created_at 為事件建立時間。平台在事件落庫後立即觸發投遞，待發通知連續發送，不設每秒或每輪固定條數限制；實際投遞時間取決於接收方與網路。首次投遞失敗後，平台最多自動重試 5 次，間隔為 30、60、120、240、480 秒，指數退避上限為 15 分鐘，包括首次在內最多投遞 6 次。平台重投原事件，不重新辦理業務或扣款。", "parameters": [ { "name": "X-RM-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "wifi_calling.item.succeeded", "wifi_calling.item.failed", "wifi_calling.job.completed" ] }, "description": "與 JSON type 一致。" }, { "name": "X-RM-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string", "example": "delivery_example" }, "description": "本次投遞嘗試編號，重投時改變；使用 JSON id 作為穩定事件去重鍵。" }, { "name": "X-RM-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[a-f0-9]{64}$" }, "description": "sha256= 加原始請求體的 HMAC-SHA256 十六進制簽名；密鑰為渠道 Webhook Secret。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "已驗簽、持久化並去重" } } } } } } } }, "/jobs": { "get": { "tags": [ "任務" ], "summary": "查詢任務列表或按交易號查單", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "partial" ] } }, { "name": "txid", "in": "query", "schema": { "type": "string" }, "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 1000000 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, { "$ref": "#/components/schemas/JobDetail" } ] }, "meta": { "$ref": "#/components/schemas/Meta" }, "pagination": { "$ref": "#/components/schemas/ExtensionPagination" } }, "required": [ "data", "meta" ] } } }, "description": "請求完成；業務結果以逐卡狀態為準", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "未找到本渠道的資料", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "交易號衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "交易號衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "查詢服務異常；收費請求結果不明時先查原交易號", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "查詢服務異常；收費請求結果不明時先查原交易號", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "get__jobs", "description": "列表回應附帶 pagination（page、per_page、total、has_more），列表為已同步快照。按批次 txid 返回整批；按逐卡 txid 只返回該條明細。指定 txid 查詢處理中任務時補取一次原批次結果；已完成任務直接返回。" } }, "/jobs/{id}": { "get": { "tags": [ "任務" ], "summary": "讀取任務及逐卡結果", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "description": "請求完成；業務結果以逐卡狀態為準", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "未找到本渠道的資料", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "405": { "description": "請求方法不支援", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求方法不支援", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string", "enum": [ "GET" ] } } } }, "409": { "description": "交易號衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "交易號衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "查詢服務異常；收費請求結果不明時先查原交易號", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "查詢服務異常；收費請求結果不明時先查原交易號", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "get__jobs_id_", "description": "按任務 ID 或批次 txid 查詢整批；按逐卡 txid 只返回匹配明細，match=item_txid。處理中任務補取一次原批次結果；未發送任務不因查詢而發單。已收到完整最終回呼的任務直接返回，不額外查詢。補查失敗時保留待確認狀態及 last_error。" } }, "/jobs/{id}/items": { "get": { "tags": [ "任務" ], "summary": "讀取逐卡結果", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "processing", "succeeded", "failed" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobItem" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "description": "請求完成；業務結果以逐卡狀態為準", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "未找到本渠道的資料", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "405": { "description": "請求方法不支援", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求方法不支援", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string", "enum": [ "GET" ] } } } }, "409": { "description": "交易號衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "交易號衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "查詢服務異常；收費請求結果不明時先查原交易號", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "查詢服務異常；收費請求結果不明時先查原交易號", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "get__jobs_id_items", "description": "返回該批次的逐卡結果，可按 status 篩選；返回該批全部匹配明細，不分頁。處理中任務補取一次原批次結果，無需逐卡查詢。" } }, "/jobs/{id}/items/{itemId}/retry": { "post": { "tags": [ "任務" ], "summary": "重試可重試的失敗明細", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "retried": { "type": "string" }, "txid": { "type": "string", "description": "提交的批次交易號為 1–64 位字母、數字、點、底線、冒號或連字符，渠道內唯一。重複提交返回 409，請查詢原任務。返回的逐卡交易號：單條與批次相同，多條為批次 txid_卡號後八位，最長 73 位。" } } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "description": "已安排重試，不代表業務成功", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "402": { "description": "餘額不足，未提交", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_balance", "message": "餘額不足，未提交", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "description": "未找到本渠道的資料", "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "405": { "description": "請求方法不支援", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求方法不支援", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string", "enum": [ "POST" ] } } } }, "409": { "description": "交易號衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "交易號衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "413": { "description": "請求內容過大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求內容過大", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "415": { "description": "需要 JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "需要 JSON", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "查詢服務異常；收費請求結果不明時先查原交易號", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "查詢服務異常；收費請求結果不明時先查原交易號", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "operationId": "post__jobs_id_items_itemId_retry", "description": "失敗明細預設保留失敗結果並進入異常待解決，不自動重試。僅在核實後主動呼叫本介面，且 retryable=true、有原任務及明細編號時，才按原參數和報價排隊重試；不要求 attempt_count 必返。發送前校驗餘額，200 表示已安排，最終結果需查詢或等待回呼。修改參數需新建請求；處理中和未知結果只查單。", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false }, "example": {} } } } } }, "/jobs/{id}/resume": { "post": { "tags": [ "任務" ], "summary": "儲值後恢復暫停任務", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "已安排處理", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "402": { "description": "餘額不足，未提交", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_balance", "message": "餘額不足，未提交", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "未找到本渠道的資料", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "405": { "description": "請求方法不支援", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求方法不支援", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string", "enum": [ "POST" ] } } } }, "409": { "description": "狀態不允許", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "狀態不允許", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "413": { "description": "請求內容過大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求內容過大", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "415": { "description": "需要 JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "需要 JSON", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "description": "儲值後恢復餘額不足的暫停任務，重新校驗餘額並沿用原報價；受理不扣款。", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false }, "example": {} } } } } }, "/jobs/{id}/recheck": { "post": { "tags": [ "任務" ], "summary": "補查結果待確認任務", "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "已安排處理", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道或能力未開放", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道或能力未開放", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "未找到本渠道的資料", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "未找到本渠道的資料", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "405": { "description": "請求方法不支援", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求方法不支援", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string", "enum": [ "POST" ] } } } }, "409": { "description": "狀態不允許", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "狀態不允許", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "413": { "description": "請求內容過大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求內容過大", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "415": { "description": "需要 JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "需要 JSON", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "請求過於頻繁，請參考 Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "請求過於頻繁，請參考 Retry-After", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "description": "只查詢原任務，不重新提交辦理請求。首次確認成功時正常記帳，重複查詢不重複扣款。", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false }, "example": {} } } } } }, "/cards/{iccid}/esim": { "get": { "summary": "讀取本渠道 eSIM 安裝資料", "parameters": [ { "name": "iccid", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{18,22}$" } } ], "responses": { "200": { "description": "查詢完成", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "iccid": { "type": "string" }, "activation_string": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "iccid", "activation_string", "created_at" ] }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道停用", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "目前渠道無此資源", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "目前渠道無此資源", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "重複編號內容衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "重複編號內容衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "限流；按 Retry-After 秒數重試", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "限流；按 Retry-After 秒數重試", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "業務服務異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "業務服務異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "description": "返回本渠道已提供的 LPA 安裝字串，不生成新的安裝碼；未提供為 404。資料敏感，不要公開緩存或記錄完整值。", "tags": [ "庫存與地區" ], "security": [ { "channelAccount": [], "apiKeyAuth": [] } ] } }, "/cards/{iccid}/sync": { "post": { "summary": "同步已歸屬卡的號碼、套餐及狀態", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "查詢完成", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "iccid": { "type": "string" }, "mdn": { "type": "string", "nullable": true }, "enrollment_id": { "type": "string", "nullable": true }, "plan_code": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "free", "active", "inactive" ] }, "upstream_line_status": { "type": "string", "nullable": true }, "last_synced_at": { "type": "string", "nullable": true } }, "required": [ "iccid", "mdn", "enrollment_id", "plan_code", "status", "upstream_line_status", "last_synced_at" ] }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道停用", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "目前渠道無此資源", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "目前渠道無此資源", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "重複編號內容衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "重複編號內容衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "413": { "description": "請求內容過大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "請求內容過大", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "415": { "description": "需要 JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "需要 JSON", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "限流；按 Retry-After 秒數重試", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "限流；按 Retry-After 秒數重試", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "業務服務異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "業務服務異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "parameters": [ { "name": "iccid", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{18,22}$" } } ], "description": "核對卡狀態與線路記錄後更新已登記資料，不創建業務訂單、不扣款。每次一張，傳空 JSON 物件；辦理中的卡、無法唯一匹配的套餐或號碼衝突拒絕同步。", "tags": [ "庫存與地區" ], "security": [ { "channelAccount": [], "apiKeyAuth": [] } ] } }, "/balance": { "get": { "summary": "渠道預存款餘額", "parameters": [], "responses": { "200": { "description": "查詢完成", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExtensionWallet" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道停用", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "目前渠道無此資源", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "目前渠道無此資源", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "重複編號內容衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "重複編號內容衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "限流；按 Retry-After 秒數重試", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "限流；按 Retry-After 秒數重試", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "業務服務異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "業務服務異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "tags": [ "帳戶與帳單" ], "security": [ { "channelAccount": [], "apiKeyAuth": [] } ] } }, "/cards": { "get": { "summary": "本渠道卡號", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "查詢完成", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExtensionCard" } }, "pagination": { "$ref": "#/components/schemas/ExtensionPagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道停用", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "目前渠道無此資源", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "目前渠道無此資源", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "重複編號內容衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "重複編號內容衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "限流；按 Retry-After 秒數重試", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "限流；按 Retry-After 秒數重試", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "業務服務異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "業務服務異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "tags": [ "庫存與地區" ], "security": [ { "channelAccount": [], "apiKeyAuth": [] } ] } }, "/ledger": { "get": { "summary": "本渠道儲值和消耗明細", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "description": "開始日期，按 America/New_York（華盛頓特區）計算，含當天，自動處理夏令時" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "description": "結束日期，按 America/New_York（華盛頓特區）計算，含當天，自動處理夏令時" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "查詢完成", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExtensionLedgerEntry" } }, "pagination": { "$ref": "#/components/schemas/ExtensionPagination" }, "summary": { "$ref": "#/components/schemas/ExtensionLedgerSummary" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "summary", "meta" ] } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道停用", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "目前渠道無此資源", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "目前渠道無此資源", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "重複編號內容衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "重複編號內容衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "限流；按 Retry-After 秒數重試", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "限流；按 Retry-After 秒數重試", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "業務服務異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "業務服務異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "description": "日期為資金實際入帳 / 扣款時間；不傳日期查詢全部。summary 覆蓋全部篩選結果，不受分頁影響。金額均為 USD 字串。", "tags": [ "帳戶與帳單" ], "security": [ { "channelAccount": [], "apiKeyAuth": [] } ] } }, "/ledger/summary": { "get": { "summary": "本渠道資金期間匯總", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "description": "開始日期，按 America/New_York（華盛頓特區）計算，含當天，自動處理夏令時" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "description": "結束日期，按 America/New_York（華盛頓特區）計算，含當天，自動處理夏令時" } } ], "responses": { "200": { "description": "查詢完成", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExtensionLedgerSummary" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道停用", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "目前渠道無此資源", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "目前渠道無此資源", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "重複編號內容衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "重複編號內容衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "限流；按 Retry-After 秒數重試", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "限流；按 Retry-After 秒數重試", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "業務服務異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "業務服務異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "description": "期初餘額為 from 之前的餘額；期末 = 期初 + 期間儲值 - 期間消耗；current_balance 為目前餘額。無 from 時期初為 0。", "tags": [ "帳戶與帳單" ], "security": [ { "channelAccount": [], "apiKeyAuth": [] } ] } }, "/ledger/export": { "get": { "summary": "導出本渠道完整帳單 CSV", "description": "UTF-8 BOM，按入帳時間升序；覆蓋全部日期篩選結果，忽略 page/per_page。長編號前加單引號避免表格軟體截斷。", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "description": "開始日期，按 America/New_York（華盛頓特區）計算，含當天，自動處理夏令時" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "description": "結束日期，按 America/New_York（華盛頓特區）計算，含當天，自動處理夏令時" } } ], "responses": { "200": { "description": "完整帳單", "content": { "text/csv": { "schema": { "type": "string" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道停用", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "目前渠道無此資源", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "目前渠道無此資源", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "重複編號內容衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "重複編號內容衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "限流；按 Retry-After 秒數重試", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "限流；按 Retry-After 秒數重試", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "業務服務異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "業務服務異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "tags": [ "帳戶與帳單" ], "security": [ { "channelAccount": [], "apiKeyAuth": [] } ] } }, "/regional-catalog": { "get": { "summary": "已保存的地區套餐目錄", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "zip", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{5}$" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "area_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" } }, { "name": "product_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "verification_status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "spreadsheet", "supplemented" ] } }, { "name": "orderable", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true 僅返回可下單記錄；false 或省略不按可下單狀態過濾，返回其他條件匹配的全部記錄。" } ], "responses": { "200": { "description": "查詢完成", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExtensionRegionalCatalog" } }, "pagination": { "$ref": "#/components/schemas/ExtensionPagination" }, "summary": { "type": "object" }, "sync": { "type": "object", "nullable": true }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道停用", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "目前渠道無此資源", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "目前渠道無此資源", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "重複編號內容衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "重複編號內容衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "限流；按 Retry-After 秒數重試", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "限流；按 Retry-After 秒數重試", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "業務服務異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "業務服務異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "description": "平台提供的地區套餐與服務地址組合目錄。可讀取不代表全部業務均可辦理，需同時檢查 orderable 和對應操作報價。只返回本渠道售價，summary 為全篩選匯總。", "tags": [ "庫存與地區" ], "security": [ { "channelAccount": [], "apiKeyAuth": [] } ] } }, "/regional-catalog/{id}": { "get": { "summary": "讀取一條地區套餐及地址設定", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "查詢完成", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExtensionRegionalCatalog" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道停用", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "目前渠道無此資源", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "目前渠道無此資源", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "重複編號內容衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "重複編號內容衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "限流；按 Retry-After 秒數重試", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "限流；按 Retry-After 秒數重試", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "業務服務異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "業務服務異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "tags": [ "庫存與地區" ], "security": [ { "channelAccount": [], "apiKeyAuth": [] } ] } }, "/zip-regions": { "get": { "summary": "郵編、城市、州及參考區號", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "zip", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{5}$" } }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "area_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[2-9]\\d{2}$", "description": "地區或歷史號碼的三位區號，僅供查詢參考" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "history_status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "observed", "no_samples" ] } } ], "responses": { "200": { "description": "查詢完成", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExtensionZipRegion" } }, "pagination": { "$ref": "#/components/schemas/ExtensionPagination" }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "states": { "type": "integer" }, "observed": { "type": "integer" }, "no_samples": { "type": "integer" }, "area_codes": { "type": "integer" }, "sample_count": { "type": "integer" } }, "required": [ "total", "states", "observed", "no_samples", "area_codes", "sample_count" ] }, "notice": { "type": "string" }, "states": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code", "name" ] } }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道停用", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "目前渠道無此資源", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "目前渠道無此資源", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "重複編號內容衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "重複編號內容衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "限流；按 Retry-After 秒數重試", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "限流；按 Retry-After 秒數重試", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "業務服務異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "業務服務異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "description": "只讀地區資料，按 ZIP 返回記錄。city_issued_area_codes 僅含同城市同州已確認實開區號，成功開卡後自動更新，不將模擬、失敗、待確認、續費或重新啟用作為新發號記錄。area_codes 合併歷史與已確認記錄，兩者均為空時回退地區參考；area_code、q 及 summary.area_codes 沿用該口徑。sample_count、history_status、summary 樣本數只統計原導入 ZIP 記錄。城市計數不可跨郵編相加，確認樣本與歷史樣本也可能重疊。區號不代表實時庫存，不能指定或保證分配。查詢不收取業務費用。地區資料更新不替代目錄 service_address 或改變 revision。", "tags": [ "庫存與地區" ], "security": [ { "channelAccount": [], "apiKeyAuth": [] } ] } }, "/zip-regions/{zip}": { "get": { "summary": "讀取一個郵編的地區與參考區號資料", "parameters": [ { "name": "zip", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{5}$" } } ], "responses": { "200": { "description": "查詢完成", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExtensionZipRegion" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "400": { "description": "參數錯誤", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "參數錯誤", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "401": { "description": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "渠道帳戶或 API Key 無效；請檢查設定或金鑰是否已重置。", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "403": { "description": "渠道停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "渠道停用", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "404": { "description": "目前渠道無此資源", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "目前渠道無此資源", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "409": { "description": "重複編號內容衝突或狀態衝突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "重複編號內容衝突或狀態衝突", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "429": { "description": "限流；按 Retry-After 秒數重試", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "限流；按 Retry-After 秒數重試", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" } } } }, "500": { "description": "內部異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "內部異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } }, "502": { "description": "業務服務異常", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upstream_error", "message": "業務服務異常", "details": { "business_code": "BUSINESS_ERROR_CODE" } }, "meta": { "request_id": "req_example" } } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" } } } } }, "tags": [ "庫存與地區" ], "security": [ { "channelAccount": [], "apiKeyAuth": [] } ] } } }, "security": [ { "channelAccount": [], "apiKeyAuth": [] } ], "externalDocs": { "description": "接入說明", "url": "https://api.roguemobile.hk/docs/guide.html?lang=zh-Hant" }, "x-documentation-language": "zh-Hant" }