整合使用 API

金鑰管理

在個人設定頁面建立和註銷 API 金鑰（需要 Business plan）。金鑰僅在建立時完整顯示一次；後續所有介面調用均須在 X-API-Key 請求標頭中攜帶。

當前開放的端點

API 金鑰驅動與 Web 介面相同的核心服務端點。當前文檔重點說明兩類自動化流程：/api/v1/axis 下的坐標轉換服務，以及 /api/v1/quality-analysis 下的品質分析服務。方案限制（每日任務數、檔案大小）與網頁主控台保持一致。

坐標轉換介面

向 POST /api/v1/axis/transform 發送來源與目標 CRS、坐標點集及 X-API-Key 標頭。介面回應返回與 Axis 工作區相同的資料結構，包含完整的轉換路徑資訊。CRS 檢索與參考框架查詢亦在同一路徑前綴下提供。

品質分析完整流程

1. 上傳觀測檔案：發起 POST /api/v1/quality-analysis/upload（multipart/form-data 格式，欄位名稱為 files，每次最多 20 個檔案），並附加 X-API-Key 標頭。回應中將返回每個檔案的對應記錄。
2. 建立分析任務：發起 POST /api/v1/quality-analysis/tasks，傳入 JSON {"config": {"tool": "<mode id>"}, "files": [<步驟 1 返回的檔案記錄>]}。模式標識包含："fast" 對應 Fast Mode，"flash" 對應 Flash Mode，"full" 對應 Full Mode，"teqc" 對應 TEQC Mode。
3. 輪詢 GET /api/v1/quality-analysis/tasks/{taskId} 直到狀態變為 completed；完成後的回應將包含完整的綜合品質結果物件。
4. 匯出 PDF 報告：透過 GET /api/v1/quality-analysis/tasks/{taskId}/report.pdf 獲取專業品質分析報告文檔。

Webhooks 非同步通知

無需反覆輪詢，註冊 Webhook 後 PosFlow 會在任務處理完畢時主動發送通知。在 /api/v1/webhooks 端點下管理 Webhooks: POST 建立（請求體包含 url、events，以及可選的 secret 與 description），GET 查看列表，DELETE /api/v1/webhooks/{id} 刪除，POST /api/v1/webhooks/{id}/test 發送模擬測試通知。接收網址必須為公網可存取的 https 協定；私有和內部 IP 位址將被系統拒絕。

Webhook 事件與酬載格式

當前支援三類事件：品質分析或處理任務成功結束時觸發 "analysis.completed"；格式轉換任務終結時分別觸發 "processing.completed" 或 "processing.failed"。每次推送均為 JSON POST 請求，包含 event、timestamp、全域唯一 id 與攜帶任務詳情的 data 物件。事件名稱同時在 X-Webhook-Event 標頭中註明。

簽章驗證與可靠性保障

若配置了 secret 密鑰，每次回呼推送均會在 X-POSFLOW-Signature 請求標頭中提供請求體的原始 HMAC-SHA256 簽章（格式為 "sha256=<hex>"；X-Webhook-Signature 則攜帶純十六進位字元）。接收端使用預留 secret 計算雜湊後比對校驗。投遞失敗將以指數退避演算法自動重試最多 3 次；連續失敗超過 10 次的 Webhook 將被自動停用，因此請確保接收伺服器快速返回 2xx 狀態並進行非同步業務處理。

調用頻率規範

所有請求均根據套裝方案受速率限制。推薦合理使用批次介面，在遇到錯誤時引入退避重試；在進行持續性大批量解算前，請提前聯絡技術支援以便合理協調運算資源。