FarmOS Land Portfolio
Acompanhe terras próprias e arrendadas, termos de arrendamento, relacionamentos com proprietários, pagamentos e custos anuais de terras.
CRÍTICO: Regras de Completude de Dados
NUNCA use dados parciais ou truncados. Estas regras são inegociáveis:
- NUNCA use
/api/integration/dashboard— ele trunca os resultados para 5 itens. Dados parciais de pagamento são piores do que nenhum dado, pois criam uma falsa sensação de completude. - SEMPRE use os endpoints
/alllistados abaixo para dados completos. - Se um endpoint retornar um erro ou resultados vazios, RELATE A FALHA ao usuário. Não recorra silenciosamente a um endpoint diferente ou apresente dados parciais.
- SEMPRE informe a contagem total de registros retornados para que o usuário saiba que os dados estão completos. Exemplo: "Encontrados 11 pagamentos com vencimento em março totalizando $175.058."
- Se você não conseguir obter dados completos, diga isso explicitamente. "Não foi possível recuperar dados completos de pagamento" é infinitamente melhor do que mostrar 5 de 11 pagamentos.
Quando Esta Skill é Acionada
- "Quando expiram nossos arrendamentos?"
- "Qual é o aluguel do terreno do Smith?"
- "Custos totais de terra este ano?"
- "Mostrar pagamentos em atraso"
- "Informações de contato do proprietário"
- "Custo por acre por parcela"
- "Listar todas as parcelas arrendadas"
- "Quais pagamentos vencem em março?"
- "Necessidades de caixa para o próximo mês"
- "Marcar pagamento [X] como pago"
- "Marcar todos os pagamentos de março como pagos"
- "Renovar o arrendamento do Smith"
- "Visualizar renovações de arrendamento"
Controle de Acesso
Termos de arrendamento, valores de aluguel e informações do proprietário são dados comerciais sensíveis. Restrito apenas a funções de administrador ou gerente.
Mapeamento de funções: Verifique a função do remetente em ~/.openclaw/farmos-users.json. Se o usuário não for administrador ou gerente, informe que ele não tem acesso aos dados do portfólio de terras.
URL Base da API
Endpoints de Integração (Sem Autenticação Necessária) — SOMENTE OPERAÇÕES DE LEITURA
IMPORTANTE: Use endpoints autenticados para operações de GRAVAÇÃO (marcar como pago, renovações). Use endpoints /all de integração para operações de LEITURA (listar pagamentos, arrendamentos, proprietários).
Pagamentos (COMPLETO — use este, não o dashboard)
GET /api/integration/payments/all
- Retorna TODOS os pagamentos com detalhes completos — nomes de parcelas, nomes de proprietários, status de atraso
- 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— início do intervalo de datas (YYYY-MM-DD)due_date_to— fim do intervalo de datas (YYYY-MM-DD)crop_year— filtrar por ano-safra
- Exemplos:
- Todos em atraso:
/api/integration/payments/all?status=overdue - Pagamentos de março de 2026:
/api/integration/payments/all?due_date_from=2026-03-01&due_date_to=2026-03-31 - Todos os pagamentos de aluguel:
/api/integration/payments/all?payment_type=rent
- Todos em atraso:
Próximos Pagamentos (próximos N dias)
GET /api/integration/payments/upcoming?days=30
- Retorna TODOS os próximos pagamentos dentro de N dias (sem truncamento)
- Use
days=60oudays=90para um horizonte maior
Arrendamentos (COMPLETO)
GET /api/integration/leases/all
- Retorna TODOS os arrendamentos com informações de contato do proprietário, termos de aluguel, status de expiração
- Parâmetros de consulta:
status— active, expiredlandlord_id— filtrar por proprietário
Arrendamentos a Expirar
GET /api/integration/leases/expiring?days=90
- Retorna TODOS os arrendamentos que expiram dentro de N dias
Proprietários (COMPLETO)
GET /api/integration/landlords/all
- Retorna TODOS os proprietários com informações de contato, contagem de arrendamentos ativos, acres totais, aluguel total
Parcelas
GET /api/integration/parcels
- Retorna TODAS as parcelas com tipo de propriedade, acres, condado
- Parâmetro de consulta:
ownership_type— owned, leased
Estatísticas Resumidas
GET /api/integration/summary
- Total de acres, divisão própria/arrendada, contagens de parcelas/arrendamentos/proprietários, custo anual
Custos Anuais de Terra (por mês e entidade)
GET /api/integration/finance/costs?year=2026
- Detalhamento mensal de custos por categoria (aluguel, hipoteca, imposto, seguro)
- Detalhamento por entidade
- Parâmetros de consulta:
year,entity_id
Custo por Campo (para P&L)
GET /api/integration/finance/cost-per-field?year=2026
- Custos de terra alocados aos campos de produção
- Parâmetros de consulta:
year,entity_id
Itens em Atraso
GET /api/integration/tasks/overdue
- Todos os pagamentos e lembretes em atraso — itens de alta prioridade
Itens Acionáveis
GET /api/integration/tasks/actionable?days_ahead=30
- Próximos pagamentos, arrendamentos a expirar, lembretes pendentes
Endpoints Autenticados — OPERAÇÕES DE GRAVAÇÃO
Estes exigem autenticação JWT. Consulte a seção de Autenticação abaixo.
Autenticação
Esta skill acessa endpoints protegidos do FarmOS que exigem um token JWT.
Para obter um token: Execute o auxiliar de autenticação com a função apropriada:
TOKEN=$(~/clawd/scripts/farmos-auth.sh admin)
Para usar o token: Inclua-o como um token Bearer:
curl -H "Authorization: Bearer $TOKEN" http://100.102.77.110:8009/api/endpoint
Expiração do token: Os tokens duram 15 minutos. Se você receber uma resposta 401, solicite um novo token.
Marcar Pagamento Único como Pago
POST /api/payments/{id}/mark-paid Authorization: Bearer {token} Content-Type: application/json
Body:
{
"paid_date": "2026-02-15",
"notes": "Cheque #1234"
}
Marcar Múltiplos Pagamentos como Pagos (Em Lote)
POST /api/payments/bulk/mark-paid Authorization: Bearer {token} Content-Type: application/json
Body:
{
"payment_ids": [12, 34, 56],
"paid_date": "2026-02-15",
"notes": "Execução de cheques em lote"
}
Marcar Pagamentos como Pagos por Intervalo de Datas
POST /api/payments/bulk/mark-paid-by-date Authorization: Bearer {token} Content-Type: application/json
Body:
{
"due_date_from": "2026-03-01",
"due_date_to": "2026-03-31",
"paid_date": "2026-02-15",
"payment_type": "rent",
"notes": "Pagamentos de aluguel de março"
}
Use este endpoint quando o usuário disser "marcar todos os pagamentos de março como pagos" ou operações semelhantes baseadas em data em lote.
Visualizar Renovação de Arrendamento
POST /api/leases/renewal-preview Authorization: Bearer {token} Content-Type: application/json
Body:
{
"lease_ids": [5, 12],
"new_start_date": "2027-03-01",
"rent_increase_percent": 3.0
}
Retorna: Visualização de como seriam os arrendamentos renovados, incluindo novos cronogramas de pagamento. Use ANTES de executar renovações em lote para que o usuário possa confirmar.
Executar Renovação em Lote de Arrendamento
POST /api/leases/bulk-renew Authorization: Bearer {token} Content-Type: application/json
Body:
{
"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": "Renovação anual com aumento de 3%"
}
IMPORTANTE: Sempre visualize primeiro, confirme com o usuário e depois execute.
Visualizar Transição de Final de Ano
POST /api/payments/year-end-rollover/preview Authorization: Bearer {token} Content-Type: application/json
Body:
{
"from_year": 2026,
"to_year": 2027
}
Retorna: Visualização dos cronogramas de pagamento que seriam criados para o novo ano-safra.
Executar Transição de Final de Ano
POST /api/payments/year-end-rollover/execute Authorization: Bearer {token} Content-Type: application/json
Body:
{
"from_year": 2026,
"to_year": 2027,
"apply_rent_increase": true,
"rent_increase_percent": 2.5
}
IMPORTANTE: Isso cria os cronogramas de pagamento do próximo ano com base nos arrendamentos do ano atual. Sempre visualize primeiro.
Endpoints PROIBIDOS — Não Use
| Endpoint | Motivo |
|---|---|
GET /api/integration/dashboard | Trunca para 5 itens. NUNCA use isso. |
Conceitos Chave
- Parcela: Uma unidade de terra — própria ou arrendada.
- Tipos de arrendamento: Aluguel em dinheiro, parceria agrícola, aluguel flexível.
- Expiração do arrendamento: Crítico de acompanhar — expirações próximas precisam de atenção proativa.
- Pagamentos de terra: Aluguel, hipoteca, imposto predial, seguro — cada um com datas de vencimento.
Notas de Uso
- O acompanhamento da expiração do arrendamento é a consulta de maior valor — sempre sinalize arrendamentos que expiram dentro de 6 meses.
- O status do pagamento (vencido/em atraso) é crítico — sinalize pagamentos em atraso imediatamente.
- A análise de custo por acre ajuda a comparar a economia de terras próprias versus arrendadas.
- As informações de contato do proprietário são privadas — nunca compartilhe fora dos canais de administrador/gerente.
- Quando perguntado sobre "necessidades de caixa" ou "o que devemos", sempre use
/api/integration/payments/allcom filtragem de data para obter a imagem COMPLETA. - Para perguntas de planejamento financeiro, combine
/api/integration/payments/allcom/api/integration/finance/costspara a visão completa. - Operações de gravação: Sempre use endpoints autenticados para marcar pagamentos como pagos ou renovar arrendamentos. Visualize primeiro ao fazer operações em lote.
- Marcação em lote de pagamentos: Quando o usuário disser "marcar todos os pagamentos de março como pagos", use o endpoint de data em lote em vez de chamadas individuais.