Portefeuille Foncier FarmOS
Suivez les terrains possédés et loués, les conditions de bail, les relations avec les propriétaires, les paiements et les coûts fonciers annuels.
CRITIQUE : Règles d'Exhaustivité des Données
N'utilisez JAMAIS de données partielles ou tronquées. Ces règles sont non négociables :
- N'utilisez JAMAIS
/api/integration/dashboard— il tronque les résultats à 5 éléments. Des données de paiement partielles sont pires que l'absence de données car elles créent un faux sentiment d'exhaustivité. - Utilisez TOUJOURS les endpoints
/alllistés ci-dessous pour des données complètes. - Si un endpoint renvoie une erreur ou des résultats vides, SIGNALEZ L'ÉCHEC à l'utilisateur. Ne basculez pas silencieusement vers un autre endpoint et ne présentez pas de données partielles.
- Indiquez TOUJOURS le nombre total d'enregistrements retournés pour que l'utilisateur sache que les données sont complètes. Exemple : "11 paiements dus en mars pour un total de 175 058 $ trouvés."
- Si vous ne pouvez pas obtenir des données complètes, dites-le explicitement. "Je n'ai pas pu récupérer les données de paiement complètes" est infiniment mieux que d'afficher 5 paiements sur 11.
Quand cette compétence se déclenche
- "Quand nos baux expirent-ils ?"
- "Quel est le loyer du terrain Smith ?"
- "Coûts fonciers totaux cette année ?"
- "Afficher les paiements en retard"
- "Coordonnées du propriétaire"
- "Coût par acre par parcelle"
- "Lister toutes les parcelles louées"
- "Quels sont les paiements dus en mars ?"
- "Besoins de trésorerie pour le mois prochain"
- "Marquer le paiement [X] comme payé"
- "Marquer tous les paiements de mars comme payés"
- "Renouveler le bail Smith"
- "Aperçu des renouvellements de baux"
Contrôle d'Accès
Les conditions de bail, les montants des loyers et les informations sur les propriétaires sont des données commerciales sensibles. Réservez l'accès aux rôles administrateur ou gestionnaire.
Mappage des rôles : Vérifiez le rôle de l'expéditeur dans ~/.openclaw/farmos-users.json. Si l'utilisateur n'est pas administrateur ou gestionnaire, dites-lui qu'il n'a pas accès aux données du portefeuille foncier.
Base API
Endpoints d'Intégration (Sans Authentification) — OPÉRATIONS DE LECTURE UNIQUEMENT
IMPORTANT : Utilisez les endpoints authentifiés pour les opérations d'ÉCRITURE (marquage payé, renouvellements). Utilisez les endpoints /all d'intégration pour les opérations de LECTURE (liste des paiements, baux, propriétaires).
Paiements (COMPLET — utilisez celui-ci, pas le tableau de bord)
GET /api/integration/payments/all
- Retourne TOUS les paiements avec tous les détails — noms des parcelles, noms des propriétaires, statut de retard
- Paramètres de requête :
status— pending, paid, overdue, scheduledpayment_type— rent, mortgage, property_tax, insurance, improvement, otherparcel_id— filtrer par parcelle spécifiquedue_date_from— début de plage YYYY-MM-DDdue_date_to— fin de plage YYYY-MM-DDcrop_year— filtrer par année culturale
- Exemples :
- Tous en retard :
/api/integration/payments/all?status=overdue - Paiements mars 2026 :
/api/integration/payments/all?due_date_from=2026-03-01&due_date_to=2026-03-31 - Tous les loyers :
/api/integration/payments/all?payment_type=rent
- Tous en retard :
Paiements à Venir (N prochains jours)
GET /api/integration/payments/upcoming?days=30
- Retourne TOUS les paiements à venir dans N jours (sans troncature)
- Utilisez
days=60oudays=90pour un horizon plus long
Baux (COMPLET)
GET /api/integration/leases/all
- Retourne TOUS les baux avec les coordonnées du propriétaire, les conditions de loyer, le statut d'expiration
- Paramètres de requête :
status— active, expiredlandlord_id— filtrer par propriétaire
Baux Expirant
GET /api/integration/leases/expiring?days=90
- Retourne TOUS les baux expirant dans N jours
Propriétaires (COMPLET)
GET /api/integration/landlords/all
- Retourne TOUS les propriétaires avec coordonnées, nombre de baux actifs, total d'acres, loyer total
Parcelles
GET /api/integration/parcels
- Retourne TOUTES les parcelles avec type de propriété, acres, comté
- Paramètre de requête :
ownership_type— owned, leased
Statistiques Résumées
GET /api/integration/summary
- Total d'acres, répartition possédé/loué, nombre de parcelles/baux/propriétaires, coût annuel
Coûts Fonciers Annuels (par mois et par entité)
GET /api/integration/finance/costs?year=2026
- Répartition mensuelle des coûts par catégorie (loyer, hypothèque, taxe, assurance)
- Répartition par entité
- Paramètres de requête :
year,entity_id
Coût Par Champ (pour P&L)
GET /api/integration/finance/cost-per-field?year=2026
- Coûts fonciers alloués aux champs de production
- Paramètres de requête :
year,entity_id
Éléments en Retard
GET /api/integration/tasks/overdue
- Tous les paiements en retard et rappels — éléments haute priorité
Éléments Actionnables
GET /api/integration/tasks/actionable?days_ahead=30
- Paiements à venir, baux expirant, rappels en attente
Endpoints Authentifiés — OPÉRATIONS D'ÉCRITURE
Ces endpoints nécessitent une authentification JWT. Voir la section Authentification ci-dessous.
Authentification
Cette compétence accède aux endpoints FarmOS protégés qui nécessitent un jeton JWT.
Pour obtenir un jeton : Exécutez le helper d'authentification avec le rôle approprié :
TOKEN=$(~/clawd/scripts/farmos-auth.sh admin)
Pour utiliser le jeton : Incluez-le comme jeton Bearer :
curl -H "Authorization: Bearer $TOKEN" http://100.102.77.110:8009/api/endpoint
Expiration du jeton : Les jetons durent 15 minutes. Si vous recevez une réponse 401, demandez un nouveau jeton.
Marquer un Paiement Unique Comme Payé
POST /api/payments/{id}/mark-paid Authorization: Bearer {token} Content-Type: application/json
Corps :
{
"paid_date": "2026-02-15",
"notes": "Chèque #1234"
}
Marquer Plusieurs Paiements Comme Payés (Groupé)
POST /api/payments/bulk/mark-paid Authorization: Bearer {token} Content-Type: application/json
Corps :
{
"payment_ids": [12, 34, 56],
"paid_date": "2026-02-15",
"notes": "Lots de chèques"
}
Marquer les Paiements Payés par Plage de Dates
POST /api/payments/bulk/mark-paid-by-date Authorization: Bearer {token} Content-Type: application/json
Corps :
{
"due_date_from": "2026-03-01",
"due_date_to": "2026-03-31",
"paid_date": "2026-02-15",
"payment_type": "rent",
"notes": "Paiements de loyer de mars"
}
Utilisez ceci lorsque l'utilisateur dit "marquer tous les paiements de mars comme payés" ou des opérations groupées similaires basées sur des dates.
Aperçu du Renouvellement de Bail
POST /api/leases/renewal-preview Authorization: Bearer {token} Content-Type: application/json
Corps :
{
"lease_ids": [5, 12],
"new_start_date": "2027-03-01",
"rent_increase_percent": 3.0
}
Retourne : Un aperçu de ce à quoi ressembleraient les baux renouvelés, y compris les nouveaux échéanciers de paiement. Utilisez ceci AVANT d'exécuter des renouvellements groupés afin que l'utilisateur puisse confirmer.
Exécuter le Renouvellement Groupé de Baux
POST /api/leases/bulk-renew Authorization: Bearer {token} Content-Type: application/json
Corps :
{
"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": "Renouvellement annuel avec augmentation de 3%"
}
IMPORTANT : Faites toujours un aperçu d'abord, confirmez avec l'utilisateur, puis exécutez.
Aperçu du Report de Fin d'Année
POST /api/payments/year-end-rollover/preview Authorization: Bearer {token} Content-Type: application/json
Corps :
{
"from_year": 2026,
"to_year": 2027
}
Retourne : Un aperçu des échéanciers de paiement qui seraient créés pour la nouvelle année culturale.
Exécution du Report de Fin d'Année
POST /api/payments/year-end-rollover/execute Authorization: Bearer {token} Content-Type: application/json
Corps :
{
"from_year": 2026,
"to_year": 2027,
"apply_rent_increase": true,
"rent_increase_percent": 2.5
}
IMPORTANT : Cela crée les échéanciers de paiement de l'année prochaine sur la base des baux de l'année en cours. Faites toujours un aperçu d'abord.
Endpoints INTERDITS — à Ne PAS Utiliser
| Endpoint | Raison |
|---|---|
GET /api/integration/dashboard | Tronque à 5 éléments. Ne JAMAIS utiliser. |
Concepts Clés
- Parcelle : Une unité foncière — possédée ou louée.
- Types de bail : Loyer en espèces, part de récolte, loyer flexible.
- Expiration du bail : Critique à suivre — les expirations à venir nécessitent une attention proactive.
- Paiements fonciers : Loyer, hypothèque, taxe foncière, assurance — chacun avec des dates d'échéance.
Notes d'Utilisation
- Le suivi des expirations de baux est la requête à plus forte valeur ajoutée — signalez toujours les baux expirant dans les 6 mois.
- Le statut des paiements (dû/en retard) est critique — signalez immédiatement les paiements en retard.
- L'analyse du coût par acre aide à comparer l'économie des terrains possédés vs loués.
- Les coordonnées des propriétaires sont privées — ne les partagez jamais en dehors des canaux administrateur/gestionnaire.
- Lorsqu'on vous interroge sur les "besoins de trésorerie" ou "ce que nous devons", utilisez toujours
/api/integration/payments/allavec un filtre de dates pour obtenir l'image COMPLÈTE. - Pour les questions de planification financière, combinez
/api/integration/payments/allavec/api/integration/finance/costspour une vue d'ensemble. - Opérations d'écriture : Utilisez toujours les endpoints authentifiés pour marquer les paiements comme payés ou renouveler les baux. Faites d'abord un aperçu pour les opérations groupées.
- Marquage groupé de paiements : Lorsque l'utilisateur dit "marquer tous les paiements de mars comme payés", utilisez l'endpoint groupé par date plutôt que des appels individuels.