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.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(`空闲单元: ${units.data.length} / ${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 处理维护请求和付款跟踪。