FarmOS 토지 포트폴리오은(는) 무엇을 하나요?
소유 및 임대 토지, 임대 조건, 임대인 관계, 지불 내역 및 연간 토지 비용을 추적합니다.
중요: 데이터 완전성 규칙
부분 데이터나 잘린 데이터는 절대 사용하지 마십시오. 다음 규칙은 협상 불가능합니다:
/api/integration/dashboard를 절대 사용하지 마십시오 — 결과를 5개 항목으로 자릅니다. 부분 지불 데이터는 완전한 데이터가 없는 것보다 더 나쁩니다. 잘못된 완전성 인식을 만들기 때문입니다.- 아래 나열된
/all엔드포인트를 항상 사용하여 완전한 데이터를 얻으십시오. - 엔드포인트가 오류를 반환하거나 빈 결과를 반환하면, 실패를 사용자에게 보고하십시오. 다른 엔드포인트로 자동 전환하거나 부분 데이터를 제시하지 마십시오.
- 반환된 레코드의 총 개수를 항상 명시하여 사용자가 데이터가 완전함을 알 수 있도록 하십시오. 예: "3월에 만기인 지불 11건, 총 $175,058을 찾았습니다."
- 완전한 데이터를 얻을 수 없으면 명시적으로 말하십시오. "완전한 지불 데이터를 검색할 수 없었습니다"는 11건 중 5건의 지불을 보여주는 것보다 훨씬 낫습니다.
이 스킬이 트리거되는 경우
- "임대가 언제 만료되나요?"
- "Smith 땅의 임대료는 얼마인가요?"
- "올해 총 토지 비용은?"
- "연체된 지불 보여줘"
- "임대인 연락처 정보"
- "필지별 에이커당 비용"
- "모든 임대 필지 목록"
- "3월에 만기인 지불은 무엇인가요?"
- "다음 달 현금 요구 사항"
- "지불 [X]를 지불 완료로 표시"
- "모든 3월 지불을 지불 완료로 표시"
- "Smith 임대 갱신"
- "임대 갱신 미리보기"
액세스 제어
임대 조건, 임대료 금액 및 임대인 정보는 민감한 비즈니스 데이터입니다. 관리자 또는 매니저 역할로만 제한하십시오.
역할 매핑: ~/.openclaw/farmos-users.json에서 보낸 사람의 역할을 확인하십시오. 사용자가 관리자 또는 매니저가 아니면 토지 포트폴리오 데이터에 액세스할 수 없다고 알리십시오.
API 기본 주소
통합 엔드포인트 (인증 불필요) — 읽기 전용 작업
중요: 쓰기 작업(지불 완료 표시, 갱신)에는 인증 엔드포인트를 사용하십시오. 읽기 작업(지불 목록, 임대, 임대인)에는 통합 /all 엔드포인트를 사용하십시오.
지불 (전체 — 이것을 사용하십시오, 대시보드 사용 금지)
GET /api/integration/payments/all
- 모든 지불을 전체 세부 정보(필지 이름, 임대인 이름, 연체 상태)와 함께 반환합니다.
- 쿼리 매개변수:
status— pending, paid, overdue, scheduledpayment_type— rent, mortgage, property_tax, insurance, improvement, otherparcel_id— 특정 필지로 필터링due_date_from— YYYY-MM-DD 범위 시작due_date_to— YYYY-MM-DD 범위 종료crop_year— 작물 연도별 필터링
- 예시:
- 모든 연체:
/api/integration/payments/all?status=overdue - 2026년 3월 지불:
/api/integration/payments/all?due_date_from=2026-03-01&due_date_to=2026-03-31 - 모든 임대료 지불:
/api/integration/payments/all?payment_type=rent
- 모든 연체:
예정된 지불 (다음 N일)
GET /api/integration/payments/upcoming?days=30
- N일 이내의 모든 예정된 지불을 반환합니다(자르기 없음).
- 더 긴 조회 기간을 위해
days=60또는days=90을 사용하십시오.
임대 (전체)
GET /api/integration/leases/all
- 임대인 연락처 정보, 임대 조건, 만료 상태를 포함한 모든 임대를 반환합니다.
- 쿼리 매개변수:
status— active, expiredlandlord_id— 임대인별 필터링
만료 예정 임대
GET /api/integration/leases/expiring?days=90
- N일 이내에 만료되는 모든 임대를 반환합니다.
임대인 (전체)
GET /api/integration/landlords/all
- 연락처 정보, 활성 임대 수, 총 에이커, 총 임대료를 포함한 모든 임대인을 반환합니다.
필지
GET /api/integration/parcels
- 소유권 유형, 에이커, 카운티를 포함한 모든 필지를 반환합니다.
- 쿼리 매개변수:
ownership_type— owned, leased
요약 통계
GET /api/integration/summary
- 총 에이커, 소유/임대 구분, 필지/임대/임대인 수, 연간 비용
연간 토지 비용 (월 및 엔터티별)
GET /api/integration/finance/costs?year=2026
- 카테고리(임대료, 모기지, 세금, 보험)별 월별 비용 분석
- 엔터티별 분석
- 쿼리 매개변수:
year,entity_id
필드별 비용 (손익 계산서용)
GET /api/integration/finance/cost-per-field?year=2026
- 생산 필드에 할당된 토지 비용
- 쿼리 매개변수:
year,entity_id
연체 항목
GET /api/integration/tasks/overdue
- 모든 연체 지불 및 알림 — 우선 순위가 높은 항목
실행 가능한 항목
GET /api/integration/tasks/actionable?days_ahead=30
- 예정된 지불, 만료 예정 임대, 보류 중인 알림
인증된 엔드포인트 — 쓰기 작업
이들은 JWT 인증이 필요합니다. 아래 인증 섹션을 참조하십시오.
인증
이 스킬은 JWT 토큰이 필요한 보호된 FarmOS 엔드포인트에 액세스합니다.
토큰을 얻으려면: 적절한 역할로 인증 도우미를 실행하십시오:
TOKEN=$(~/clawd/scripts/farmos-auth.sh admin)
토큰을 사용하려면: Bearer 토큰으로 포함시키십시오:
curl -H "Authorization: Bearer $TOKEN" http://100.102.77.110:8009/api/endpoint
토큰 만료: 토큰은 15분 동안 유효합니다. 401 응답을 받으면 새 토큰을 요청하십시오.
단일 지불 지불 완료 표시
POST /api/payments/{id}/mark-paid Authorization: Bearer {token} Content-Type: application/json
본문:
{
"paid_date": "2026-02-15",
"notes": "Check #1234"
}
여러 지불 지불 완료 표시 (일괄)
POST /api/payments/bulk/mark-paid Authorization: Bearer {token} Content-Type: application/json
본문:
{
"payment_ids": [12, 34, 56],
"paid_date": "2026-02-15",
"notes": "Batch check run"
}
날짜 범위별 지불 지불 완료 표시
POST /api/payments/bulk/mark-paid-by-date Authorization: Bearer {token} Content-Type: application/json
본문:
{
"due_date_from": "2026-03-01",
"due_date_to": "2026-03-31",
"paid_date": "2026-02-15",
"payment_type": "rent",
"notes": "March rent payments"
}
사용자가 "모든 3월 지불을 지불 완료로 표시" 또는 이와 유사한 일괄 날짜 기반 작업을 요청할 때 이 엔드포인트를 사용하십시오.
임대 갱신 미리보기
POST /api/leases/renewal-preview Authorization: Bearer {token} Content-Type: application/json
본문:
{
"lease_ids": [5, 12],
"new_start_date": "2027-03-01",
"rent_increase_percent": 3.0
}
반환: 갱신된 임대의 미리보기(새로운 지불 일정 포함). 일괄 갱신을 실행하기 전에 사용자가 확인할 수 있도록 먼저 이 엔드포인트를 사용하십시오.
일괄 임대 갱신 실행
POST /api/leases/bulk-renew Authorization: Bearer {token} Content-Type: application/json
본문:
{
"lease_ids": [5, 12],
"new_start_date": "2027-03-01",
"new_end_date": "2028-02-28",
"new_rent_amount": 52000.00,
"rent_increase_percent": 3.0,
"notes": "Annual renewal with 3% increase"
}
중요: 항상 먼저 미리보기를 하고, 사용자와 확인한 후 실행하십시오.
연말 이월 미리보기
POST /api/payments/year-end-rollover/preview Authorization: Bearer {token} Content-Type: application/json
본문:
{
"from_year": 2026,
"to_year": 2027
}
반환: 새로운 작물 연도에 대해 생성될 지불 일정의 미리보기.
연말 이월 실행
POST /api/payments/year-end-rollover/execute Authorization: Bearer {token} Content-Type: application/json
본문:
{
"from_year": 2026,
"to_year": 2027,
"apply_rent_increase": true,
"rent_increase_percent": 2.5
}
중요: 현재 연도 임대를 기반으로 다음 연도의 지불 일정을 생성합니다. 항상 먼저 미리보기를 하십시오.
사용 금지 엔드포인트 — 사용하지 마십시오
| 엔드포인트 | 이유 |
|---|---|
GET /api/integration/dashboard | 5개 항목으로 자릅니다. 절대 사용하지 마십시오. |
주요 개념
- 필지: 토지 단위 — 소유 또는 임대.
- 임대 유형: 현금 임대료, 작물 분할, 유연 임대료.
- 임대 만료: 추적이 중요 — 다가오는 만료는 사전 대응이 필요합니다.
- 토지 지불: 임대료, 모기지, 재산세, 보험 — 각각 만기일이 있습니다.
사용 참고 사항
- 임대 만료 추적은 가장 가치 있는 쿼리입니다 — 항상 6개월 이내에 만료되는 임대에 플래그를 지정하십시오.
- 지불 상태(만기/연체)는 중요합니다 — 연체된 지불을 즉시 플래그 지정하십시오.
- 에이커당 비용 분석은 소유 대 임대 경제성을 비교하는 데 도움이 됩니다.
- 임대인 연락처 정보는 비공개입니다 — 관리자/매니저 채널 외부에서 절대 공유하지 마십시오.
- "현금 요구 사항" 또는 "우리가 빚진 것"에 대해 물을 때는 항상
/api/integration/payments/all을 날짜 필터링과 함께 사용하여 완전한 그림을 얻으십시오. - 재무 계획 질문의 경우, 전체 보기를 위해
/api/integration/payments/all과/api/integration/finance/costs를 결합하십시오. - 쓰기 작업: 지불 완료 표시 또는 임대 갱신을 위해 항상 인증된 엔드포인트를 사용하십시오. 일괄 작업을 수행할 때는 먼저 미리보기를 하십시오.
- 일괄 지불 표시: 사용자가 "모든 3월 지불을 지불 완료로 표시"라고 말하면 개별 호출 대신 일괄 날짜별 엔드포인트를 사용하십시오.