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 | 缺少类别或 property_id | 根据架构包含所有必填字段 |
409 Conflict | 工单已关闭 | 在尝试关闭前检查状态 |
429 Rate Limited | 超过 120 次请求/分钟 | 添加指数退避,基本延迟 1 秒 |
输出
成功运行会创建一个工单,将其指派给具有预定服务窗口的供应商,并使用成本记录和解决说明关闭工单。物业经理将获得从请求到完成的完整审计轨迹。
示例
对于沙箱管道工作流,使用稳定的幂等键创建一个合成工单,指派一个沙箱供应商,并在任何状态转换前读取其状态。仅附加一个非敏感的测试收据,然后一次性关闭订单,并验证总额和审计记录,而不记录租户或访问详细信息。重复同一请求以证明重复工单和重复成本记录会被拒绝。如果供应商指派、安全分类、先前状态或关闭结果不确定,则保持工单开放并将其路由给授权的物业运营商进行审查。
资源
后续步骤
关于身份验证设置和分页辅助工具,请参见 appfolio-sdk-patterns。