AppFolio 安裝與驗證
總覽
設定 AppFolio Stack API 驗證。AppFolio 使用 HTTP Basic Auth,搭配用戶端 ID 和用戶端密碼,透過其 Stack 合作夥伴計畫提供。沒有公開的 npm SDK — 請直接使用 REST API 呼叫。
先決條件
- AppFolio Stack 合作夥伴帳戶 (appfolio.com/stack)
- 來自 AppFolio 的用戶端 ID 和用戶端密碼
- Node.js 18+ 或 Python 3.10+
操作說明
步驟 1:取得 API 憑證
# AppFolio Stack API 憑證來自合作夥伴計畫
# 1. 在 appfolio.com/stack/become-a-partner 申請
# 2. 完成整合審查
# 3. 接收提供者核發的基礎 URL 和憑證傳遞說明。
# 將值存放於核准的機密管理器中。若需要本地開發,請僅提交此非機密範本:
cat > .env.example << 'ENVFILE'
APPFOLIO_CLIENT_ID=
APPFOLIO_CLIENT_SECRET=
APPFOLIO_BASE_URL=
ENVFILE
# .env 保持忽略;僅透過核准的本地機密流程來填入。
步驟 2:建立 API 用戶端
// src/appfolio-client.ts
import axios, { AxiosInstance } from 'axios';
class AppFolioClient {
private api: AxiosInstance;
constructor() {
this.api = axios.create({
baseURL: process.env.APPFOLIO_BASE_URL,
auth: {
username: process.env.APPFOLIO_CLIENT_ID!,
password: process.env.APPFOLIO_CLIENT_SECRET!,
},
headers: { 'Content-Type': 'application/json' },
timeout: 30000,
});
}
async verifyConnection(): Promise<boolean> {
try {
const response = await this.api.get('/properties');
console.log(`已連線!找到 ${response.data.length} 個物業`);
return true;
} catch (error: any) {
console.error(`連線失敗:${error.response?.status} ${error.message}`);
return false;
}
}
get http(): AxiosInstance { return this.api; }
}
export { AppFolioClient };
步驟 3:驗證連線
# 快速、遮罩的診斷,不在 argv 中放入 Basic Auth。
NETRC_FILE="$(mktemp)"
trap 'rm -f "$NETRC_FILE"' EXIT
chmod 600 "$NETRC_FILE"
APPFOLIO_HOST="${APPFOLIO_BASE_URL#https://}"
APPFOLIO_HOST="${APPFOLIO_HOST%%/*}"
printf 'machine %s login %s password %s\n' "$APPFOLIO_HOST" \
"$APPFOLIO_CLIENT_ID" "$APPFOLIO_CLIENT_SECRET" > "$NETRC_FILE"
curl -s -o /dev/null -w '%{http_code}\n' --netrc-file "$NETRC_FILE" \
"${APPFOLIO_BASE_URL}/properties"
API 端點
| 資源 | 端點 | 方法 |
|---|---|---|
| 物業 | /api/v1/properties | GET |
| 單位 | /api/v1/units | GET |
| 租戶 | /api/v1/tenants | GET |
| 租約 | /api/v1/leases | GET, POST |
| 帳單 | /api/v1/bills | GET, POST |
| 供應商 | /api/v1/vendors | GET |
| 業主 | /api/v1/owners | GET |
| 報表 | /api/v1/reports | GET |
輸出
- 透過核准的機密邊界注入提供者核發的憑證
- 帶有 Basic Auth 的 TypeScript REST 用戶端
- 對核准的唯讀端點進行遮罩式連線結果
範例
若要進行首次驗證排練,請透過本地機密機制注入沙箱憑證和提供者核發的基礎 URL,然後對核准的合成物業頁面發送一次唯讀請求。僅記錄狀態碼和用戶端配置判斷結果;請勿在共享日誌中列印物業承載、用戶端 ID、密碼或完整的 host/path。如果合約、基礎 URL、機密繫結或狀態結果未經驗證,請在執行任何寫入工作流程之前停止,並讓憑證擁有者修正配置。
錯誤處理
| 錯誤 | 原因 | 解決方案 |
|---|---|---|
401 Unauthorized | 無效憑證 | 驗證來自 AppFolio 的 client_id/secret |
403 Forbidden | 非 Stack 合作夥伴 | 完成合作夥伴申請 |
404 Not Found | 基礎 URL 錯誤 | 使用 your-company.appfolio.com 格式 |
| 逾時 | 網路問題 | 檢查防火牆是否允許 HTTPS 到 appfolio.com |
資源
後續步驟
前往 appfolio-hello-world 進行你的首次物業查詢。