AppFolio — 物件&テナント管理
概要
AppFolio 物件管理統合の主要ワークフローです。物件レコードの作成・更新、テナントプロフィールと賃貸契約の管理、占有データのクエリといった物件ライフサイクル全体をカバーします。OAuth 2.0 クライアント認証情報を使用したサーバー間アクセスで AppFolio Stack API を利用します。すべてのエンドポイントは JSON を返し、大規模ポートフォリオ向けに cursor パラメータによるページネーションをサポートします。
前提条件
- 割り当てられたポートフォリオのベースURL、認証方法、承認済みスコープ、書き込み機能を確認する、有効な AppFolio パートナー/API 契約。チュートリアルや他のポートフォリオからこれらを推測しないでください。
- 使い捨て可能な物件、ユニット、および合成テナントレコード、さらに認証情報所有者と承認済みリクエスト予算を備えた、別のサンドボックス。
- 物件、テナント、賃貸契約の書き込みに関する冪等性キーとオペレーター承認済みのロールバック/調整プロセス。実際の法的および請求上の影響が生じる可能性があります。
手順
- クライアント設定を環境にコピーする前に、対象ポートフォリオに対してプロバイダー発行のベース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が確認できます。
例
賃貸契約作成の変更の場合、名前付きの合成サンドボックスユニットとテナントに対して、安定した冪等性キーを使用して実行します。物件と現在の賃貸契約を読み取り、候補となる書き込みを1回実行し、結果の賃貸契約を読み戻して、ID、日付、および調整ステータスのみを記録します。同じリクエストを再実行して、2番目の賃貸契約が作成されないことを確認します。プロバイダー契約、エンドポイント、認証、または事前の書き込み結果が検証できない場合は、書き込み前に停止し、調整のためにポートフォリオオペレーターにケースを送信します。
リソース
次のステップ
保守リクエストと支払い追跡については、appfolio-core-workflow-b に進んでください。