Endpoints de Análise Financeira

Visão Geral

Os endpoints de Análise Financeira permitem:

• Rastrear despesas operacionais por categoria
• Calcular custo por kg em tempo real
• Analisar lucratividade com métricas de ROI
• Prever momento ideal de despesca com IA

---

POST /financial/expenses

Registra uma despesa operacional.

Headers

Authorization: Bearer <token>

Body da Requisição

{
  "batch_id": "batch-uuid",
  "category": "FEED",
  "amount": 5000.50,
  "description": "Compra de ração - Janeiro",
  "expense_date": "2026-01-08T00:00:00Z"
}

Categorias de Despesa

Categoria	Descrição
FEED	Custos de ração
LABOR	Custos de mão de obra
ENERGY	Custos de energia
MAINTENANCE	Custos de manutenção
SUPPLIES	Suprimentos e materiais
TREATMENT	Tratamento de doenças
TRANSPORT	Transporte
EQUIPMENT	Compra de equipamentos
OTHER	Outras despesas

Resposta 201 Created

{
  "id": "expense-uuid",
  "batch_id": "batch-uuid",
  "category": "FEED",
  "amount": 5000.50,
  "description": "Compra de ração - Janeiro",
  "expense_date": "2026-01-08T00:00:00Z",
  "created_at": "2026-01-08T10:30:00Z"
}

---

GET /financial/cost-per-kg/{batch_id}

Calcula o custo de produção por quilograma.

Parâmetros de Path

Nome	Tipo	Descrição
batch_id	UUID	Identificador do lote

Resposta 200 OK

{
  "batch_id": "batch-uuid",
  "batch_number": "LOTE-2026-001",
  "estimated_biomass_kg": 1062.5,
  "total_feed_cost": 5000.50,
  "total_operational_cost": 1500.00,
  "total_energy_cost": 0.0,
  "total_cost": 6500.50,
  "cost_per_kg": 6.12,
  "breakdown": {
    "feed_percentage": 76.92,
    "operational_percentage": 23.08,
    "energy_percentage": 0.0
  }
}

Nota

Custos de energia ainda não estão disponíveis. Serão integrados através de SensorData em versões futuras.

Fórmula de Cálculo

Custo por Kg = (Custo de Ração + Custo Operacional) / Biomassa

---

GET /financial/profitability/{batch_id}

Analisa a lucratividade do lote.

Parâmetros de Path

Nome	Tipo	Descrição
batch_id	UUID	Identificador do lote

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
selling_price_per_kg	float	✅	Preço de venda esperado por kg

Exemplo

GET /api/v1/financial/profitability/batch-uuid?selling_price_per_kg=18.50

Resposta 200 OK

{
  "batch_id": "batch-uuid",
  "estimated_biomass_kg": 1062.5,
  "cost_per_kg": 6.12,
  "selling_price_per_kg": 18.50,
  "total_cost": 6500.50,
  "projected_revenue": 19656.25,
  "projected_profit": 13155.75,
  "profit_margin_percentage": 66.93,
  "roi_percentage": 202.32
}

Métricas Calculadas

• Receita Projetada: Biomassa × Preço de Venda
• Lucro Projetado: Receita - Custo Total
• Margem de Lucro: (Lucro / Receita) × 100
• ROI: (Lucro / Custo Total) × 100

---

GET /financial/optimal-harvest/{batch_id}

Previsão do momento ideal de despesca baseado em IA.

Parâmetros de Path

Nome	Tipo	Descrição
batch_id	UUID	Identificador do lote

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
market_price_per_kg	float	✅	Preço de mercado atual por kg
daily_operational_cost	float	❌	Custo operacional diário (padrão: 100.0)

Exemplo

GET /api/v1/financial/optimal-harvest/batch-uuid?market_price_per_kg=18.50&daily_operational_cost=150.0

Resposta 200 OK

{
  "batch_id": "batch-uuid",
  "recommendation": "CONTINUE",
  "explanation": "Receita de crescimento diário (R$ 177.60) excede o custo diário (R$ 150.00). Continue crescendo.",
  "analysis": {
    "current_weight_g": 5.0,
    "expected_daily_growth_g": 0.15,
    "current_biomass_kg": 1062.5,
    "daily_biomass_gain_kg": 31.875,
    "daily_growth_revenue": 177.60,
    "daily_operational_cost": 150.0,
    "net_daily_profit": 27.60
  },
  "suggestion": "Monitorar taxa de crescimento. Despeque quando receita_diária < custo_diário"
}

Valores de Recomendação

Valor	Descrição
CONTINUE	Continuar crescendo - lucrativo
HARVEST_NOW	Despeque agora - não é mais lucrativo esperar
MONITOR	Monitoramento próximo necessário

Algoritmo de IA

O algoritmo considera taxa de crescimento, preço de mercado e custos operacionais para maximizar o lucro.

Lógica de Decisão

SE (crescimento_diário × preço_mercado) > custo_diário_operacional
  ENTÃO CONTINUAR
SENÃO DESPEQUE_AGORA

---

Fluxo de Trabalho Típico

1. Registrar Despesas - POST /financial/expenses conforme ocorrem
2. Monitorar Custo - GET /financial/cost-per-kg/{id} periodicamente
3. Avaliar Lucratividade - GET /financial/profitability/{id} com preço de mercado
4. Decidir Despesca - GET /financial/optimal-harvest/{id} para timing ideal

---

Relatórios Futuros

Funcionalidades planejadas para versões futuras:

• Análise de tendências de custo ao longo do tempo
• Comparação entre lotes históricos
• Previsão de custos baseada em padrões
• Integração com dados de mercado em tempo real
• Alertas de custo acima do esperado