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를 확인합니다.
예제
임대 생성 변경의 경우, 안정적인 멱등성 키와 함께 명명된 합성 샌드박스 유닛 및 세입자에 대해 실행합니다. 부동산 및 현재 임대를 읽고, 후보 쓰기를 한 번 수행한 다음, 결과 임대를 다시 읽고 ID, 날짜 및 조정 상태만 기록합니다. 동일한 요청을 다시 실행하여 두 번째 임대가 생성되지 않음을 증명합니다. 제공자 계약, 엔드포인트, 권한 부여 또는 이전 쓰기 결과를 확인할 수 없는 경우, 쓰기 전에 중단하고 포트폴리오 운영자에게 조정을 위해 사례를 전달합니다.
리소스
다음 단계
유지 보수 요청 및 지불 추적을 위해 appfolio-core-workflow-b로 계속 진행하십시오.