AppFolio 安装与认证
概览
配置 AppFolio Stack API 身份认证。AppFolio 使用 HTTP 基本认证,需要客户端 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 中。
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 |
输出
- 通过已批准的密钥边界注入提供商颁发的凭据
- 带基本认证的 TypeScript REST 客户端
- 针对已批准的安全读取端点的连接结果(已脱敏)
示例
对于首次认证演练,通过本地密钥机制注入沙箱凭据和提供商颁发的基础 URL,然后向一个已批准的合成属性页面发起一次只读请求。仅记录状态码和客户端配置结论;不要在共享日志中打印属性负载、客户端 ID、密钥或完整的主机/路径。如果合同、基础 URL、密钥绑定或状态结果未经验证,请在执行任何写入工作流之前停止,并让凭据所有者修正配置。
错误处理
| 错误 | 原因 | 解决方法 |
|---|---|---|
401 Unauthorized | 无效凭据 | 向 AppFolio 验证客户端 ID/密钥 |
403 Forbidden | 不是 Stack 合作伙伴 | 完成合作伙伴申请 |
404 Not Found | 基础 URL 错误 | 使用 your-company.appfolio.com 格式 |
| 超时 | 网络问题 | 检查防火墙是否允许 HTTPS 连接到 appfolio.com |
参考资料
后续步骤
继续执行 appfolio-hello-world 以进行您的首次属性查询。