AppFolio — 作業指示とメンテナンス
概要
AppFolio の Stack API を通じて、メンテナンス作業指示のライフサイクル全体を管理します。
次のような場合にこのワークフローを使用します:テナントがメンテナンス依頼を提出したとき、ベンダーを未処理の作業指示に割り当てるとき、物件全体の修理進捗を追跡するとき、または完了したジョブをコスト記録と共にクローズするとき。これは二次的なワークフローです。物件ダッシュボードやリース業務については、appfolio-core-workflow-a を参照してください。
前提条件
- 検証済みの AppFolio 契約、および仮想的な物件、ユニット、ベンダー、作業指示レコードを含むサンドボックス ポートフォリオ。占有中の本番ユニットに対してメンテナンス自動化をテストしないでください。
- 最小権限のサービス ID、作成/クローズ操作に対するべき等性(idempotency)のサポート、および安全上重要なメンテナンスに対する承認済みエスカレーションパス。
- データ最小化ポリシー:作業の実行に必要なメンテナンス情報のみを保存・送信し、テナントの嗜好、アクセスコード、または詳細な居住情報を汎用的なベンダーノートやログに含めないこと。
手順
ステップ 1: メンテナンス依頼から作業指示を作成する
const workOrder = await client.workOrders.create({
property_id: 'prop_4821',
unit_id: 'unit_12B',
category: 'plumbing',
priority: 'high',
description: 'サンドボックスユニットで報告された仮想的な配管器具の漏れ',
requested_by: 'tenant_8934',
due_date: '2026-04-10',
});
console.log(`作業指示 ${workOrder.id} が作成されました — ステータス: ${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: '承認された作業指示チャネルを通じて予約の確認を行ってください。',
});
console.log(`${assignment.scheduled_date} に ${assignment.vendor_name} に割り当てられました`);
ステップ 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} (期限 ${wo.due_date})`)
);
ステップ 4: 作業指示をコスト記録と共にクローズする
const closed = await client.workOrders.close(workOrder.id, {
resolution: 'Pトラップを交換し、給水ラインを締め付けました。それ以降漏れはありません。',
labor_cost: 175.00,
materials_cost: 42.50,
completed_date: '2026-04-08',
attachments: ['receipt_plumb_0408.pdf'],
});
console.log(`#${closed.id} をクローズ — 合計費用: $${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 秒の指数バックオフを追加 |
出力
成功すると、作業指示が作成され、スケジュールされたサービス時間枠でベンダーに割り当てられ、コスト記録と解決メモと共にクローズされます。物件管理者は、依頼から完了までの完全な監査証跡を取得できます。
例
サンドボックス配管ワークフローでは、安定したべき等性キーで 1 つの仮想的な作業指示を作成し、サンドボックスベンダーを割り当て、ステータス遷移前にそのステータスを読み戻します。機密性のないテスト用領収書のみを添付し、その後一度だけ作業指示をクローズして、合計と監査レコードを確認します(テナントやアクセスの詳細はログに記録しません)。同じリクエストを再生して、重複する作業指示と重複するコスト記録が拒否されることを証明します。ベンダーの割り当て、安全分類、以前の状態、またはクローズ結果が不明確な場合は、作業指示をオープンのままにし、承認された物件管理者にルーティングして確認を依頼します。
リソース
次のステップ
認証設定とページネーションヘルパーについては appfolio-sdk-patterns を参照してください。