AppFolio — 工單與維護管理 是做什麼的?
概述
透過 AppFolio 的 Stack API 管理維護工單的完整生命週期。
當租戶提交維護請求、需要指派供應商給未處理工單、跨物業追蹤維修進度,或使用成本記錄完成已完工工作時,可使用此工作流程。這是次要工作流程——如需查看物業儀表板與租賃功能,請參閱 appfolio-core-workflow-a。
先決條件
- 已驗證的 AppFolio 合約與沙盒組合,包含合成物業、單元、供應商及工單記錄;請勿在已入住的正式單元上測試維護自動化。
- 使用最低權限的服務身分、支援建立/關閉操作的冪等性,以及針對安全關鍵性維護的已核准升級路徑。
- 數據最小化政策:僅儲存及傳輸執行工作所需的維護事實,切勿在通用供應商備註或日誌中儲存租戶偏好、存取碼或詳細居住資訊。
操作說明
步驟 1:從維護請求建立工單
const workOrder = await client.workOrders.create({
property_id: 'prop_4821',
unit_id: 'unit_12B',
category: 'plumbing',
priority: 'high',
description: 'Synthetic plumbing fixture leak reported in sandbox unit',
requested_by: 'tenant_8934',
due_date: '2026-04-10',
});
console.log(`Work order ${workOrder.id} created — status: ${workOrder.status}`);
步驟 2:指派供應商
const assignment = await client.workOrders.assign(workOrder.id, {
vendor_id: 'vendor_plumb_01',
scheduled_date: '2026-04-08',
time_window: '09:00-12:00',
notes: 'Confirm scheduled appointment through the approved work-order channel.',
});
console.log(`Assigned to ${assignment.vendor_name} on ${assignment.scheduled_date}`);
步驟 3:追蹤工單狀態
const open = await client.workOrders.list({
property_id: 'prop_4821',
status: ['open', 'in_progress', 'scheduled'],
sort: 'priority_desc',
});
open.items.forEach(wo =>
console.log(`#${wo.id} [${wo.priority}] ${wo.category} — ${wo.status} (due ${wo.due_date})`)
);
步驟 4:關閉工單並記錄成本
const closed = await client.workOrders.close(workOrder.id, {
resolution: 'Replaced P-trap and tightened supply line. No further leaks.',
labor_cost: 175.00,
materials_cost: 42.50,
completed_date: '2026-04-08',
attachments: ['receipt_plumb_0408.pdf'],
});
console.log(`Closed #${closed.id} — total cost: $${closed.total_cost}`);
錯誤處理
| 問題 | 原因 | 解決方法 |
|---|---|---|
401 Unauthorized | API 憑證過期或無效 | 在 Stack 儀表板中更新 client_id/secret |
404 Work Order Not Found | 工單 ID 錯誤或已被刪除 | 使用 workOrders.list() 驗證 ID |
422 Missing required fields | 遺漏 category 或 property_id 等必要欄位 | 根據綱要包含所有必要欄位 |
409 Conflict | 工單已關閉 | 在嘗試關閉前檢查狀態 |
429 Rate Limited | 超過每分鐘 120 次請求限制 | 加入指數退避策略,基本延遲 1 秒 |
輸出
成功執行後會建立工單、指派給供應商並排定服務時段,最後以成本記錄和解決方案備註完成關閉。物業經理將獲得從請求到完成的完整稽核軌跡。
範例
對於沙盒水管工作流程,請使用穩定的冪等金鑰建立一個合成工單,指派一個沙盒供應商,並在任何轉換前讀取其狀態。僅附加非敏感的測試收據,然後一次性關閉工單,並驗證總金額與稽核記錄,而不記錄租戶或存取詳細資訊。重複相同的請求以證明重複工單和重複成本記錄會被拒絕。如果供應商指派、安全分類、先前狀態或關閉結果不確定,請保持工單開啟,並交由授權的物業操作人員審查。
資源
後續步驟
請參閱 appfolio-sdk-patterns 以了解認證設定與分頁輔助功能。