AppFolio — 物業與租戶管理
概覽
AppFolio 物業管理整合的主要工作流程。涵蓋完整的物業生命週期:建立與更新物業記錄、管理租戶檔案與租約協議,以及查詢入住率資料。使用 AppFolio Stack API,並透過 OAuth 2.0 用戶端憑證進行伺服器對伺服器的存取。所有端點皆回傳 JSON,並支援透過 cursor 參數分頁處理大型物業組合。
先決條件
- 一份有效的 AppFolio 合作夥伴/API 合約,其中需確認指派的物業組合基礎 URL、驗證方法、已核准的範圍,以及寫入能力;不得從教學或其他物業組合推斷這些資訊。
- 一個獨立的沙盒環境,包含可拋棄的物業、單元與合成租戶記錄,以及一個憑證擁有者和已核准的請求預算。
- 針對物業、租戶與租約寫入操作的冪等性金鑰,以及營運者核准的回滾/復原程序,因為這些操作可能會產生實際的法律與帳務後果。
指示
- 在將任何用戶端設定複製到環境之前,先確認提供者針對目標物業組合發行的基礎 URL 與驗證流程。
- 僅在沙盒中使用合成測試資料與冪等性金鑰來執行建立/更新路徑;在不確定的寫入操作重試前,先取得正規記錄。
- 在建立租約之前,驗證所有權、租約日期與單元可用性,並僅輸出記錄 ID 與經過編輯的狀態證據。
- 只有在階段性排練證明回滾、復原以及最低權限範圍邊界可行之後,才推廣具寫入能力的流程。
步驟 1:驗證並初始化客戶端
const token = await fetch('https://api.appfolio.com/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'client_credentials',
client_id: process.env.APPFOLIO_CLIENT_ID!,
client_secret: process.env.APPFOLIO_CLIENT_SECRET!,
scope: 'properties tenants leases',
}),
}).then(r => r.json());
const headers = { Authorization: `Bearer ${token.access_token}`, 'Content-Type': 'application/json' };
步驟 2:建立或更新物業
const property = await fetch('https://api.appfolio.com/v1/properties', {
method: 'POST', headers,
body: JSON.stringify({
name: 'Sunrise Apartments',
address: { street: '100 Main St', city: 'Austin', state: 'TX', zip: '78701' },
type: 'residential',
units: [
{ number: '101', bedrooms: 2, bathrooms: 1, rent: 1450 },
{ number: '102', bedrooms: 1, bathrooms: 1, rent: 1100 },
],
}),
}).then(r => r.json());
console.log(`Property created: ${property.id}`);
步驟 3:新增租戶與租約
const tenant = await fetch('https://api.appfolio.com/v1/tenants', {
method: 'POST', headers,
body: JSON.stringify({
first_name: 'Test', last_name: 'Tenant',
email: '[email protected]', phone: '555-0100',
}),
}).then(r => r.json());
await fetch('https://api.appfolio.com/v1/leases', {
method: 'POST', headers,
body: JSON.stringify({
property_id: property.id, unit_number: '101',
tenant_id: tenant.id, start_date: '2026-05-01', end_date: '2027-04-30',
monthly_rent: 1450, security_deposit: 1450,
}),
}).then(r => r.json());
步驟 4:查詢入住率
const units = await fetch(
`https://api.appfolio.com/v1/properties/${property.id}/units?status=vacant`,
{ headers },
).then(r => r.json());
console.log(`Vacant units: ${units.data.length} of ${units.meta.total}`);
錯誤處理
| 問題 | 原因 | 解決方案 |
|---|---|---|
401 Unauthorized | 憑證過期或無效 | 使用用戶端憑證重新驗證 |
404 Not Found | 錯誤的物業/租戶 ID | 在引用前確認資源 ID 存在 |
422 Unprocessable | 缺少必要欄位 | 檢查回應主體中的 errors[] 陣列 |
409 Conflict | 單元已有重複租約 | 在建立前查詢現有租約 |
429 Too Many Requests | 超過速率限制 | 根據 Retry-After 標頭值退避重試 |
輸出
成功執行後會建立包含單元的物業、新增租戶、透過租約將兩者綁定,並回報空置單元數量。主控台會在建立時輸出每個資源 ID。
範例
對於租約建立變更,請針對指定的命名合成沙盒單元與租戶,使用穩定的冪等性金鑰執行。先讀取物業與當前租約,執行一次候選寫入,然後回讀產生的租約,僅記錄 ID、日期與復原狀態。重複執行相同請求以證明不會建立第二份租約。如果無法驗證提供者合約、端點、授權或先前寫入結果,請在寫入前停止,並將案件轉交給物業組合營運者進行復原。
資源
下一步
繼續使用 appfolio-core-workflow-b 進行維護請求與付款追蹤。