AppFolio 安装与认证
概述
配置 AppFolio Stack API 认证。AppFolio 使用带有客户端 ID 和客户端密钥的 HTTP Basic Auth,这些凭证通过其 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. 收到 client_id 和 client_secret
cat > .env << 'ENVFILE'
APPFOLIO_CLIENT_ID=your-client-id
APPFOLIO_CLIENT_SECRET=your-client-secret
APPFOLIO_BASE_URL=https://your-company.appfolio.com/api/v1
ENVFILE
chmod 600 .env
echo ".env" >> .gitignore
步骤 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:验证连接
# 快速 curl 测试
curl -u "${APPFOLIO_CLIENT_ID}:${APPFOLIO_CLIENT_SECRET}" \
"${APPFOLIO_BASE_URL}/properties" | jq '.[0]'
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 |
输出
- 在
.env中配置的 API 凭证 - 带 Basic Auth 的 TypeScript REST 客户端
- 已验证的 AppFolio API 连接
错误处理
| 错误 | 原因 | 解决办法 |
|---|---|---|
401 Unauthorized | 无效凭证 | 从 AppFolio 验证 client_id/secret |
403 Forbidden | 非 Stack 合作伙伴 | 完成合作伙伴申请 |
404 Not Found | 错误的 base URL | 使用 your-company.appfolio.com 格式 |
| 超时 | 网络问题 | 检查防火墙是否允许通过 HTTPS 连接到 appfolio.com |
资源
下一步
继续进行 appfolio-hello-world 以执行您的第一个物业查询。