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. 공급자가 발급한 기본 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단계: 연결 확인
# Basic Auth를 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 |
출력
- 공급자가 발급한 자격 증명(승인된 비밀 경계를 통해 주입)
- Basic Auth를 사용하는 TypeScript REST 클라이언트
- 승인된 안전 읽기 엔드포인트에 대한 연결 결과(수정된 형태)
예시
첫 번째 인증 연습을 위해, 샌드박스 자격 증명과 공급자가 발급한 기본 URL을 로컬 비밀 메커니즘을 통해 주입한 후, 승인된 합성 속성 페이지에 대해 읽기 전용 요청을 한 번 수행하세요. 상태 코드와 클라이언트 구성 판단만 기록하고, 속성 페이로드, 클라이언트 ID, 시크릿 또는 전체 호스트/경로를 공유 로그에 출력하지 마세요. 계약, 기본 URL, 비밀 바인딩 또는 상태 결과가 확인되지 않은 경우, 쓰기 워크플로우 전에 중단하고 자격 증명 소유자가 구성을 수정하도록 하세요.
오류 처리
| 오류 | 원인 | 해결 방법 |
|---|---|---|
401 Unauthorized | 잘못된 자격 증명 | AppFolio에서 client_id/secret 확인 |
403 Forbidden | Stack 파트너가 아님 | 파트너 신청 완료 |
404 Not Found | 잘못된 기본 URL | your-company.appfolio.com 형식 사용 |
| 타임아웃 | 네트워크 문제 | 방화벽에서 appfolio.com HTTPS 허용 확인 |
리소스
다음 단계
첫 번째 속성 쿼리를 위해 appfolio-hello-world로 진행하세요.