Portefeuille Foncier FarmOS
Suivez les terrains possédés et loués, les conditions des baux, les relations avec les propriétaires, les paiements et les coûts fonciers annuels.
RÈGLES CRITIQUES D'INTÉGRITÉ 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 pas de données car elles créent une fausse impression de complétude. - 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 vous rabattez pas silencieusement sur un autre endpoint et ne présentez pas de données partielles.
- Indiquez TOUJOURS le nombre total d'enregistrements renvoyés afin que l'utilisateur sache que les données sont complètes. Exemple : "11 paiements trouvés à échéance en mars pour un total de 175 058 €."
- 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 de la parcelle 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 paiements sont 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 des baux, les montants des loyers et les informations des propriétaires sont des données commerciales sensibles. Réservez l'accès aux rôles administrateur ou gestionnaire uniquement.
Correspondance 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 de l'API
Endpoints d'intégration (aucune authentification requise) — OPÉRATIONS DE LECTURE UNIQUEMENT
IMPORTANT : Utilisez les endpoints authentifiés pour les opérations d'ÉCRITURE (marquer comme 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
- Renvoie 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 (en attente), paid (payé), overdue (en retard), scheduled (planifié)payment_type— rent (loyer), mortgage (prêt immobilier), property_tax (taxe foncière), insurance (assurance), improvement (amélioration), other (autre)parcel_id— filtrer par parcelle spécifiquedue_date_from— début de la plage de dates (AAAA-MM-JJ)due_date_to— fin de la plage de dates (AAAA-MM-JJ)crop_year— filtrer par année culturale
- Exemples :
- Tous en retard :
/api/integration/payments/all?status=overdue - Paiements de 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
- Renvoie TOUS les paiements à venir dans N jours (pas de troncature)
- Utilisez
days=60oudays=90pour une anticipation plus longue
Baux (COMPLET)
GET /api/integration/leases/all
- Renvoie 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 (actif), expired (expiré)landlord_id— filtrer par propriétaire
Baux expirant
GET /api/integration/leases/expiring?days=90
- Renvoie TOUS les baux expirant dans N jours
Propriétaires (COMPLET)
GET /api/integration/landlords/all
- Renvoie TOUS les propriétaires avec leurs coordonnées, le nombre de baux actifs, le nombre total d'acres, le loyer total
Parcelles
GET /api/integration/parcels
- Renvoie TOUTES les parcelles avec le type de propriété, la superficie en acres, le comté
- Paramètre de requête :
ownership_type— owned (possédée), leased (louée)
Statistiques récapitulatives
GET /api/integration/summary
- Nombre total d'acres, répartition possédée/louée, 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, prêt immobilier, taxe, assurance)
- Répartition par entité
- Paramètres de requête :
year,entity_id
Coût par champ (pour le compte de résultat)
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 et rappels en retard — é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
Ceux-ci nécessitent une authentification JWT. Voir la section Authentification ci-dessous.
Authentification
Cette compétence accède à des endpoints FarmOS protégés qui nécessitent un jeton JWT.
Pour obtenir un jeton : Exécutez l'assistant 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 obtenez 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 (en masse)
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": "Émission groupée de chèques"
}
Marquer les paiements comme payés par fourchette 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 des loyers de mars"
}
Utilisez ceci lorsque l'utilisateur dit "marquer tous les paiements de mars comme payés" ou une autre opération groupée basée sur une date.
Prévisualiser le renouvellement d'un 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
}
Renvoie : 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 les 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.
Prévisualisation du roulement 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
}
Renvoie : Un aperçu des échéanciers de paiement qui seraient créés pour la nouvelle année culturale.
Exécution du roulement 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 : Ceci crée les échéanciers de paiement de l'année prochaine en fonction 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. N'utilisez JAMAIS ceci. |
Concepts clés
- Parcelle : Une unité foncière — possédée ou louée.
- Types de baux : Loyer en espèces, part de récolte, loyer flexible.
- Expiration du bail : Critique à suivre — les échéances approchantes nécessitent une attention proactive.
- Paiements fonciers : Loyer, prêt immobilier, taxe foncière, assurance — chacun avec des dates d'échéance.
Notes d'utilisation
- Le suivi de l'expiration des 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 entre terrains possédés et loués.
- Les coordonnées du propriétaire 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 complète. - Opérations d'écriture : Utilisez toujours les endpoints authentifiés pour marquer les paiements comme payés ou renouveler les baux. Faites un aperçu d'abord pour les opérations groupées.
- Marquage groupé des 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.