Portafolio de Tierras FarmOS
Realiza un seguimiento de tierras propias y arrendadas, términos de arrendamiento, relaciones con propietarios, pagos y costos anuales de la tierra.
CRÍTICO: Reglas de Integridad de Datos
NUNCA uses datos parciales o truncados. Estas reglas no son negociables:
- NUNCA uses
/api/integration/dashboard— trunca los resultados a 5 elementos. Los datos de pago parciales son peores que no tener datos porque crean una falsa sensación de integridad. - SIEMPRE usa los endpoints
/alllistados a continuación para obtener datos completos. - Si un endpoint devuelve un error o resultados vacíos, REPORTA EL FALLO al usuario. No recurras silenciosamente a un endpoint diferente ni presentes datos parciales.
- SIEMPRE indica el recuento total de registros devueltos para que el usuario sepa que los datos están completos. Ejemplo: "Se encontraron 11 pagos con vencimiento en marzo por un total de $175,058."
- Si no puedes obtener datos completos, dilo explícitamente. "No pude recuperar los datos de pago completos" es infinitamente mejor que mostrar 5 de 11 pagos.
Cuándo se Activa Esta Habilidad
- "¿Cuándo vencen nuestros arrendamientos?"
- "¿Cuál es la renta del terreno Smith?"
- "¿Costos totales de tierra este año?"
- "Mostrar pagos vencidos"
- "Información de contacto del propietario"
- "Costo por acre por parcela"
- "Listar todas las parcelas arrendadas"
- "¿Qué pagos vencen en marzo?"
- "Requerimientos de efectivo para el próximo mes"
- "Marcar pago [X] como pagado"
- "Marcar todos los pagos de marzo como pagados"
- "Renovar el arrendamiento de Smith"
- "Previsualizar renovaciones de arrendamientos"
Control de Acceso
Los términos de arrendamiento, montos de renta e información del propietario son datos comerciales sensibles. Restringir solo a roles de administrador o gerente.
Mapeo de roles: Verifica el rol del remitente en ~/.openclaw/farmos-users.json. Si el usuario no es administrador o gerente, indícale que no tiene acceso a los datos del portafolio de tierras.
Base de la API
Endpoints de Integración (Sin Autenticación Requerida) — SOLO OPERACIONES DE LECTURA
IMPORTANTE: Usa endpoints autenticados para operaciones de ESCRITURA (marcar como pagado, renovaciones). Usa endpoints de integración /all para operaciones de LECTURA (listar pagos, arrendamientos, propietarios).
Pagos (COMPLETO — usa esto, no el dashboard)
GET /api/integration/payments/all
- Devuelve TODOS los pagos con detalles completos: nombres de parcelas, nombres de propietarios, estado de vencimiento
- Parámetros de consulta:
status— pending, paid, overdue, scheduledpayment_type— rent, mortgage, property_tax, insurance, improvement, otherparcel_id— filtrar por parcela específicadue_date_from— inicio del rango YYYY-MM-DDdue_date_to— fin del rango YYYY-MM-DDcrop_year— filtrar por año agrícola
- Ejemplos:
- Todos los vencidos:
/api/integration/payments/all?status=overdue - Pagos de marzo 2026:
/api/integration/payments/all?due_date_from=2026-03-01&due_date_to=2026-03-31 - Todos los pagos de renta:
/api/integration/payments/all?payment_type=rent
- Todos los vencidos:
Próximos Pagos (próximos N días)
GET /api/integration/payments/upcoming?days=30
- Devuelve TODOS los pagos próximos dentro de N días (sin truncamiento)
- Usa
days=60odays=90para una vista anticipada más larga
Arrendamientos (COMPLETO)
GET /api/integration/leases/all
- Devuelve TODOS los arrendamientos con información de contacto del propietario, términos de renta, estado de vencimiento
- Parámetros de consulta:
status— active, expiredlandlord_id— filtrar por propietario
Arrendamientos por Vencer
GET /api/integration/leases/expiring?days=90
- Devuelve TODOS los arrendamientos que vencen dentro de N días
Propietarios (COMPLETO)
GET /api/integration/landlords/all
- Devuelve TODOS los propietarios con información de contacto, recuento de arrendamientos activos, acres totales, renta total
Parcelas
GET /api/integration/parcels
- Devuelve TODAS las parcelas con tipo de propiedad, acres, condado
- Parámetro de consulta:
ownership_type— owned, leased
Estadísticas Resumidas
GET /api/integration/summary
- Acres totales, desglose propio/arrendado, recuentos de parcelas/arrendamientos/propietarios, costo anual
Costos Anuales de Tierra (por mes y entidad)
GET /api/integration/finance/costs?year=2026
- Desglose mensual de costos por categoría (renta, hipoteca, impuesto, seguro)
- Desglose por entidad
- Parámetros de consulta:
year,entity_id
Costo por Campo (para PyG)
GET /api/integration/finance/cost-per-field?year=2026
- Costos de tierra asignados a campos de producción
- Parámetros de consulta:
year,entity_id
Elementos Vencidos
GET /api/integration/tasks/overdue
- Todos los pagos y recordatorios vencidos — elementos de alta prioridad
Elementos Accionables
GET /api/integration/tasks/actionable?days_ahead=30
- Próximos pagos, arrendamientos por vencer, recordatorios pendientes
Endpoints Autenticados — OPERACIONES DE ESCRITURA
Estos requieren autenticación JWT. Consulta la sección de Autenticación a continuación.
Autenticación
Esta habilidad accede a endpoints protegidos de FarmOS que requieren un token JWT.
Para obtener un token: Ejecuta el asistente de autenticación con el rol apropiado:
TOKEN=$(~/clawd/scripts/farmos-auth.sh admin)
Para usar el token: Inclúyelo como token Bearer:
curl -H "Authorization: Bearer $TOKEN" http://100.102.77.110:8009/api/endpoint
Caducidad del token: Los tokens duran 15 minutos. Si obtienes una respuesta 401, solicita un nuevo token.
Marcar un Pago Individual como Pagado
POST /api/payments/{id}/mark-paid Authorization: Bearer {token} Content-Type: application/json
Cuerpo:
{
"paid_date": "2026-02-15",
"notes": "Cheque #1234"
}
Marcar Múltiples Pagos como Pagados (Masivo)
POST /api/payments/bulk/mark-paid Authorization: Bearer {token} Content-Type: application/json
Cuerpo:
{
"payment_ids": [12, 34, 56],
"paid_date": "2026-02-15",
"notes": "Ejecución de cheques por lote"
}
Marcar Pagos como Pagados por Rango de Fechas
POST /api/payments/bulk/mark-paid-by-date Authorization: Bearer {token} Content-Type: application/json
Cuerpo:
{
"due_date_from": "2026-03-01",
"due_date_to": "2026-03-31",
"paid_date": "2026-02-15",
"payment_type": "rent",
"notes": "Pagos de renta de marzo"
}
Usa esto cuando el usuario diga "marcar todos los pagos de marzo como pagados" u operaciones masivas similares basadas en fechas.
Previsualizar Renovación de Arrendamiento
POST /api/leases/renewal-preview Authorization: Bearer {token} Content-Type: application/json
Cuerpo:
{
"lease_ids": [5, 12],
"new_start_date": "2027-03-01",
"rent_increase_percent": 3.0
}
Devuelve: Vista previa de cómo se verían los arrendamientos renovados, incluidos los nuevos calendarios de pago. Usa esto ANTES de ejecutar renovaciones masivas para que el usuario pueda confirmar.
Ejecutar Renovación Masiva de Arrendamientos
POST /api/leases/bulk-renew Authorization: Bearer {token} Content-Type: application/json
Cuerpo:
{
"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": "Renovación anual con aumento del 3%"
}
IMPORTANTE: Siempre previsualiza primero, confirma con el usuario y luego ejecuta.
Previsualización de Rollover de Fin de Año
POST /api/payments/year-end-rollover/preview Authorization: Bearer {token} Content-Type: application/json
Cuerpo:
{
"from_year": 2026,
"to_year": 2027
}
Devuelve: Vista previa de los calendarios de pago que se crearían para el nuevo año agrícola.
Ejecutar Rollover de Fin de Año
POST /api/payments/year-end-rollover/execute Authorization: Bearer {token} Content-Type: application/json
Cuerpo:
{
"from_year": 2026,
"to_year": 2027,
"apply_rent_increase": true,
"rent_increase_percent": 2.5
}
IMPORTANTE: Esto crea los calendarios de pago del próximo año basados en los arrendamientos del año actual. Siempre previsualiza primero.
Endpoints PROHIBIDOS — No Usar
| Endpoint | Por qué |
|---|---|
GET /api/integration/dashboard | Trunca a 5 elementos. NUNCA uses esto. |
Conceptos Clave
- Parcela: Una unidad de tierra, propia o arrendada.
- Tipos de arrendamiento: Renta en efectivo, participación en cosecha, renta flexible.
- Vencimiento del arrendamiento: Crítico de rastrear: las expiraciones próximas necesitan atención proactiva.
- Pagos de tierra: Renta, hipoteca, impuesto a la propiedad, seguro, cada uno con fechas de vencimiento.
Notas de Uso
- El seguimiento de vencimientos de arrendamientos es la consulta de mayor valor: siempre señala los arrendamientos que vencen dentro de los próximos 6 meses.
- El estado del pago (pendiente/vencido) es crítico: señala los pagos vencidos inmediatamente.
- El análisis de costo por acre ayuda a comparar la economía de tierras propias vs. arrendadas.
- La información de contacto del propietario es privada: nunca la compartas fuera de los canales de administración/gerencia.
- Cuando te pregunten sobre "requerimientos de efectivo" o "qué debemos", usa siempre
/api/integration/payments/allcon filtrado de fechas para obtener la imagen COMPLETA. - Para preguntas de planificación financiera, combina
/api/integration/payments/allcon/api/integration/finance/costspara una vista completa. - Operaciones de escritura: Siempre usa endpoints autenticados para marcar pagos como pagados o renovar arrendamientos. Previsualiza primero cuando se trate de operaciones masivas.
- Marcado masivo de pagos: Cuando el usuario diga "marcar todos los pagos de marzo como pagados", usa el endpoint masivo por fecha en lugar de llamadas individuales.