Cartera de Tierras FarmOS
Realiza un seguimiento de tierras propias y arrendadas, términos de arrendamiento, relaciones con propietarios, pagos y costos anuales de tierras.
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 ningún dato 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, INFORMA 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 vencidos 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 el alquiler del terreno Smith?"
- "¿Costos totales de tierras 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?"
- "Requisitos de efectivo para el próximo mes"
- "Marcar pago [X] como pagado"
- "Marcar todos los pagos de marzo como pagados"
- "Renovar el arrendamiento Smith"
- "Previsualizar renovaciones de arrendamientos"
Control de Acceso
Los términos de arrendamiento, montos de alquiler e información del propietario son datos comerciales sensibles. Restringir solo a roles de administrador o gerente.
Asignación de roles: Verifica el rol del remitente en ~/.openclaw/farmos-users.json. Si el usuario no es administrador o gerente, dile que no tiene acceso a los datos de la cartera de tierras.
Base de 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 /all de integración para operaciones de LECTURA (listar pagos, arrendamientos, propietarios).
Pagos (COMPLETO — usa este, 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— pendiente, pagado, vencido, programadopayment_type— alquiler, hipoteca, impuesto_predial, seguro, mejora, otroparcel_id— filtrar por parcela específicadue_date_from— inicio de rango YYYY-MM-DDdue_date_to— fin de rango YYYY-MM-DDcrop_year— filtrar por año de cultivo
- Ejemplos:
- Todos 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 alquiler:
/api/integration/payments/all?payment_type=rent
- Todos vencidos:
Próximos Pagos (próximos N días)
GET /api/integration/payments/upcoming?days=30
- Devuelve TODOS los próximos pagos dentro de N días (sin truncamiento)
- Usa
days=60odays=90para un horizonte más largo
Arrendamientos (COMPLETO)
GET /api/integration/leases/all
- Devuelve TODOS los arrendamientos con información de contacto del propietario, términos de alquiler, estado de vencimiento
- Parámetros de consulta:
status— activo, vencidolandlord_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, alquiler total
Parcelas
GET /api/integration/parcels
- Devuelve TODAS las parcelas con tipo de propiedad, acres, condado
- Parámetro de consulta:
ownership_type— propia, arrendada
Estadísticas Resumidas
GET /api/integration/summary
- Acres totales, desglose propio/arrendado, recuentos de parcelas/arrendamientos/propietarios, costo anual
Costos Anuales de Tierras (por mes y entidad)
GET /api/integration/finance/costs?year=2026
- Desglose mensual de costos por categoría (alquiler, hipoteca, impuesto, seguro)
- Desglose por entidad
- Parámetros de consulta:
year,entity_id
Costo Por Campo (para P&L)
GET /api/integration/finance/cost-per-field?year=2026
- Costos de tierras asignados a campos de producción
- Parámetros de consulta:
year,entity_id
Elementos Vencidos
GET /api/integration/tasks/overdue
- Todos los pagos vencidos y recordatorios — 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 en 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 alquiler 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 cronogramas 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, luego ejecuta.
Previsualización de Cierre 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 cronogramas de pago que se crearían para el nuevo año de cultivo.
Ejecutar Cierre 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 cronogramas de pago del próximo año basados en los arrendamientos del año actual. Siempre previsualiza primero.
Endpoints PROHIBIDOS — No Usar
| Endpoint | Motivo |
|---|---|
GET /api/integration/dashboard | Trunca a 5 elementos. NUNCA uses esto. |
Conceptos Clave
- Parcela: Una unidad de tierra — ya sea propia o arrendada.
- Tipos de arrendamiento: Alquiler en efectivo, participación en cosecha, alquiler flexible.
- Vencimiento del arrendamiento: Crítico de rastrear — los vencimientos próximos necesitan atención proactiva.
- Pagos de tierras: Alquiler, hipoteca, impuesto predial, seguro — cada uno con fechas de vencimiento.
Notas de Uso
- El seguimiento de vencimientos de arrendamientos es la consulta de mayor valor — siempre marca los arrendamientos que vencen en los próximos 6 meses.
- El estado del pago (vencido/no vencido) es crítico — marca 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 "requisitos 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: Usa siempre endpoints autenticados para marcar pagos como pagados o renovar arrendamientos. Previsualiza primero cuando hagas 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.