CMMS API 參考
本頁提供面向客戶的 CMMS 整合介面結構。最終 endpoint、payload 和欄位映射以客戶部署範圍和執行時 OpenAPI 為準。
API 表面
目前 API 錨點
配接器類型參考
| 類型 | 用途 |
|---|---|
webhook | 將工單事件推送到下游 endpoint，並透過入站 webhook 接收狀態回呼。 |
rest | 使用客戶批准的路徑、認證、欄位映射和結果解析配置通用 REST 設定檔。 |
maximo | 透過 Maximo REST 設定檔連接 IBM Maximo 工單。 |
sap-pm | 透過 SAP OData 設定檔連接 SAP Plant Maintenance 維護訂單。 |
| Forge 或客戶 overlay 設定檔 | 透過批准的 overlay wiring 和 payload 契約連接 Honeywell Forge 或其他客戶專項提供商。 |
BACnet、Modbus、SNMP 是設備脈絡用的現場協定配接器，不應配置為下游 CMMS 工單配接器。
| 分組 | API |
|---|---|
| CMMS 配置 | GET /api/v1/cmms/adapters, POST /api/v1/cmms/adapters, POST /api/v1/cmms/adapters/{id}/test |
| 資產映射 | GET /api/v1/cmms/asset-mappings, POST /api/v1/cmms/asset-mappings, POST /api/v1/cmms/asset-mappings/batch |
| 同步日誌 | GET /api/v1/cmms/sync/logs |
| CMMS 概覽 | GET /api/v1/cmms/dashboard-summary |
| 工單 | GET /api/v1/workorders, POST /api/v1/workorders, PUT /api/v1/workorders/{id}/assign-resource, POST /api/v1/workorders/{id}/feedback |
| 工單請求 | POST /api/v1/platform/worker-issues, POST /api/v1/platform/worker-issues/{id}/triage, POST /api/v1/platform/worker-issues/{id}/convert |
| 預測性維護連接 | GET /api/v1/pdm/cmms, POST /api/v1/pdm/cmms, POST /api/v1/pdm/advisory/{id}/work-order, POST /api/v1/pdm/advisory/{id}/outcome |
契約欄位
| 欄位 | 用途 |
|---|---|
common_work_order_id | FactVerse 工單引用。 |
provider_id | 來源 CMMS、EAM、承包商系統或整合配置。 |
source_work_order_id | 提供商原生工單 ID。 |
asset_ref | MDM 資產、設備、位置或系統引用。 |
source_status / common_status | 原始狀態和共享生命週期狀態。 |
sync_state | 匯入、待同步、已同步、重試、拒絕或陳舊。 |
錯誤處理
認證、授權、欄位校驗、資產身分、衝突和提供商不可用都應有明確的返回、同步日誌和人工處理路徑。
執行介面補充
| 能力 | 典型介面 |
|---|---|
| 技師和班組 | GET /api/v1/technicians, GET /api/v1/crews, PUT /api/v1/workorders/id/assign-resource |
| 預防性維護 | GET /api/v1/maintenance-schedules, GET /api/v1/maintenance-calendar, POST /api/v1/maintenance-completions |
| 備品和庫存 | GET /api/v1/spare-parts, GET /api/v1/inventory, POST /api/v1/inventory/transactions |
CMMS Agent 和 MCP 工具錨點
CMMS Agent 工具表面由租戶 Agent 配置限定。tools/list 只應顯示目前 Agent 綁定的 CMMS 工具。tools/call 在執行前應套用租戶範圍、權限檢查、風險上限、冪等和稽核。
| 工具 | 權限 | 契約 |
|---|---|---|
cmms_query_backlog | cmms.read | 讀取工單積壓總數、優先級分布和 SLA 違約數量。 |
cmms_query_equipment | cmms.read | 讀取設備或資產記錄，可按站點過濾。 |
cmms_query_work_orders | cmms.read | 按狀態、設備和分頁範圍讀取工單。 |
cmms_suggest_technician | cmms.read | 返回可用技師候選，不執行派工。 |
cmms_create_work_request | workorders.create | 建立申請或現場問題報告，並留下稽核記錄。 |
cmms_create_work_order | workorders.create | 在完成所需審閱或確認後建立工單。 |
cmms_assign_work_order | workorders.assign | 在確認後把工單派給技師或班組。 |
cmms_close_work_order | workorders.complete | 在確認後完成工單；完成屬於終態營運動作。 |
讀取工具通過範圍和權限檢查後執行。工單申請是帶稽核的低風險寫入。建立工單、派工和完成工單在負責人確認前應保持為需要確認的狀態。調用方重試同一邏輯動作時應傳入穩定的冪等鍵。
正式專案應以部署環境暴露的 OpenAPI 和客戶側權限矩陣為準。