AppFolio — 작업 지시서 및 유지보수
개요
AppFolio Stack API를 통해 유지보수 작업 지시서의 전체 라이프사이클을 관리합니다.
이 워크플로우는 세입자가 유지보수 요청을 제출할 때, 열려 있는 작업 지시서에 벤더를 할당해야 할 때, 여러 부동산의 수리 진행 상황을 추적해야 할 때, 또는 완료된 작업을 비용 기록과 함께 종료해야 할 때 사용합니다. 이는 보조 워크플로우입니다. 부동산 대시보드 및 임대 관련 작업은 appfolio-core-workflow-a를 참조하세요.
사전 조건
- 검증된 AppFolio 계약 및 합성 부동산, 유닛, 벤더, 작업 지시서 레코드가 있는 샌드박스 포트폴리오가 필요합니다. 실제 사용 중인 프로덕션 유닛에서 유지보수 자동화를 테스트하지 마십시오.
- 최소 권한 서비스 ID, 생성/종료 작업에 대한 멱등성(idempotency) 지원, 안전 관련 유지보수를 위한 승인된 에스컬레이션 경로가 필요합니다.
- 데이터 최소화 정책: 작업 수행에 필요한 유지보수 정보만 저장 및 전송하며, 세입자 선호도, 접근 코드, 또는 일반 벤더 노트나 로그에 상세 점유 정보를 포함하지 않습니다.
지침
1단계: 유지보수 요청에서 작업 지시서 생성
const workOrder = await client.workOrders.create({
property_id: 'prop_4821',
unit_id: 'unit_12B',
category: 'plumbing',
priority: 'high',
description: '샌드박스 유닛에서 합성 배관 설비 누수 신고',
requested_by: 'tenant_8934',
due_date: '2026-04-10',
});
console.log(`작업 지시서 ${workOrder.id} 생성됨 — 상태: ${workOrder.status}`);
2단계: 벤더 할당
const assignment = await client.workOrders.assign(workOrder.id, {
vendor_id: 'vendor_plumb_01',
scheduled_date: '2026-04-08',
time_window: '09:00-12:00',
notes: '승인된 작업 지시서 채널을 통해 예약된 약속을 확인하세요.',
});
console.log(`${assignment.vendor_name}에게 ${assignment.scheduled_date}에 할당됨`);
3단계: 작업 지시서 상태 추적
const open = await client.workOrders.list({
property_id: 'prop_4821',
status: ['open', 'in_progress', 'scheduled'],
sort: 'priority_desc',
});
open.items.forEach(wo =>
console.log(`#${wo.id} [${wo.priority}] ${wo.category} — ${wo.status} (기한 ${wo.due_date})`)
);
4단계: 비용 기록과 함께 작업 지시서 종료
const closed = await client.workOrders.close(workOrder.id, {
resolution: 'P-트랩 교체 및 공급 라인 조임. 추가 누수 없음.',
labor_cost: 175.00,
materials_cost: 42.50,
completed_date: '2026-04-08',
attachments: ['receipt_plumb_0408.pdf'],
});
console.log(`#${closed.id} 종료됨 — 총 비용: $${closed.total_cost}`);
오류 처리
| 문제 | 원인 | 해결책 |
|---|---|---|
401 Unauthorized | API 자격 증명 만료 또는 잘못됨 | Stack 대시보드에서 client_id/secret 갱신 |
404 Work Order Not Found | 잘못된 작업 지시서 ID 또는 이미 삭제됨 | workOrders.list()로 ID 확인 |
422 Missing required fields | category 또는 property_id 누락 | 스키마에 따라 필수 필드 모두 포함 |
409 Conflict | 작업 지시서가 이미 종료됨 | 종료 시도 전에 상태 확인 |
429 Rate Limited | 분당 120회 요청 초과 | 1초 기본 지연으로 지수 백오프 추가 |
출력
성공적인 실행은 작업 지시서를 생성하고, 예약된 서비스 시간 창과 함께 벤더에게 할당하며, 비용 기록 및 해결 노트와 함께 종료합니다. 부동산 관리자는 요청부터 완료까지 완전한 감사 추적을 얻습니다.
예제
샌드박스 배관 워크플로우의 경우, 안정적인 멱등성 키로 하나의 합성 작업 지시서를 생성하고, 샌드박스 벤더를 할당한 후, 어떤 전환 전에 상태를 다시 읽어보십시오. 민감하지 않은 테스트 영수증만 첨부하고, 작업을 한 번 종료한 후 총계와 감사 기록을 확인하되 세입자 또는 접근 세부 정보를 기록하지 마십시오. 동일한 요청을 재생하여 중복 작업 지시서 및 중복 비용 기록이 거부되는지 증명하십시오. 벤더 할당, 안전 분류, 이전 상태 또는 종료 결과가 불확실한 경우 작업 지시서를 열린 상태로 두고 승인된 부동산 운영자에게 라우팅하여 검토를 받으십시오.
리소스
다음 단계
인증 설정 및 페이지네이션 도우미에 대해서는 appfolio-sdk-patterns를 참조하세요.