BrainPredict Controlling: API Reference

POST /api/v1/controlling/kpis
Authorization: Bearer bp_controlling_live_xxx
Content-Type: application/json

{
  "kpi_code": "EBITDA_MARGIN",
  "kpi_name": "EBITDA Margin",
  "category": "Profitability",
  "unit": "percentage",
  "target_value": 25.0,
  "warning_threshold": 20.0,
  "critical_threshold": 15.0,
  "calculation_formula": "(EBITDA / Revenue) * 100",
  "frequency": "monthly",
  "owner": "CFO",
  "description": "EBITDA as percentage of revenue"
}

{
  "success": true,
  "kpi_id": "kpi_abc123",
  "kpi_code": "EBITDA_MARGIN",
  "kpi_name": "EBITDA Margin",
  "status": "active",
  "created_at": "2025-11-09T10:30:00Z",
  "message": "KPI created successfully"
}

POST /api/v1/controlling/forecasts/predict
Authorization: Bearer bp_controlling_live_xxx
Content-Type: application/json

{
  "historical_months": 24,
  "forecast_months": 12,
  "kpis": ["revenue", "ebitda", "cash_flow"],
  "include_scenarios": true,
  "confidence_level": 0.95,
  "ai_model": "performance_predictor"
}

{
  "success": true,
  "forecast_id": "fcst_xyz789",
  "accuracy": 94.2,
  "confidence": 95.0,
  "forecasts": {
    "revenue": {
      "12m_forecast": 125000000,
      "growth_rate": 8.5,
      "trend": "increasing"
    },
    "ebitda": {
      "12m_forecast": 31250000,
      "margin": 25.0,
      "trend": "stable"
    },
    "cash_flow": {
      "12m_forecast": 28000000,
      "conversion_rate": 89.6,
      "trend": "increasing"
    }
  },
  "scenarios": {
    "best_case": { "revenue": 135000000, "probability": 0.15 },
    "base_case": { "revenue": 125000000, "probability": 0.70 },
    "worst_case": { "revenue": 110000000, "probability": 0.15 }
  },
  "ai_insights": [
    "Revenue growth driven by product expansion",
    "EBITDA margin stable at target level",
    "Strong cash conversion expected"
  ],
  "created_at": "2025-11-09T10:35:00Z"
}

POST /api/v1/controlling/analytics/variance
Authorization: Bearer bp_controlling_live_xxx
Content-Type: application/json

{
  "period": "2025-10",
  "dimensions": ["cost_center", "product", "region"],
  "variance_threshold": 5.0,
  "include_root_cause": true,
  "ai_model": "variance_analyzer"
}

{
  "success": true,
  "analysis_id": "var_def456",
  "period": "2025-10",
  "total_variance": -850000,
  "variance_percentage": -6.8,
  "significant_variances": [
    {
      "dimension": "cost_center",
      "entity": "CC-1001 (Sales)",
      "plan": 5000000,
      "actual": 5450000,
      "variance": -450000,
      "variance_pct": -9.0,
      "root_causes": [
        "Higher commission rates due to new incentive program",
        "Increased travel expenses for customer meetings"
      ],
      "impact": "high"
    },
    {
      "dimension": "product",
      "entity": "Product A",
      "plan": 8000000,
      "actual": 7600000,
      "variance": 400000,
      "variance_pct": 5.0,
      "root_causes": [
        "Lower than expected sales volume",
        "Pricing pressure from competitors"
      ],
      "impact": "medium"
    }
  ],
  "ai_recommendations": [
    "Review sales incentive program effectiveness",
    "Investigate Product A pricing strategy",
    "Monitor competitor activities closely"
  ],
  "accuracy": 93.5
}

POST /api/v1/controlling/scenarios/simulate
Authorization: Bearer bp_controlling_live_xxx
Content-Type: application/json

{
  "scenario_name": "Price Increase 5%",
  "base_period": "2025-10",
  "simulation_months": 12,
  "assumptions": [
    {
      "variable": "price",
      "change_type": "percentage",
      "change_value": 5.0
    },
    {
      "variable": "volume",
      "change_type": "percentage",
      "change_value": -2.0,
      "reason": "Expected volume decline due to price increase"
    }
  ],
  "ai_model": "scenario_simulator"
}

{
  "success": true,
  "scenario_id": "scn_ghi789",
  "scenario_name": "Price Increase 5%",
  "simulation_results": {
    "revenue_impact": {
      "baseline": 120000000,
      "simulated": 123480000,
      "change": 3480000,
      "change_pct": 2.9
    },
    "ebitda_impact": {
      "baseline": 30000000,
      "simulated": 32370000,
      "change": 2370000,
      "change_pct": 7.9
    },
    "volume_impact": {
      "baseline": 1000000,
      "simulated": 980000,
      "change": -20000,
      "change_pct": -2.0
    }
  },
  "sensitivity_analysis": {
    "price_elasticity": -0.4,
    "break_even_volume_decline": -5.2
  },
  "ai_insights": [
    "Net positive impact on profitability despite volume decline",
    "EBITDA margin improves from 25.0% to 26.2%",
    "Recommended if volume decline stays below 5%"
  ],
  "confidence": 91.5,
  "created_at": "2025-11-09T10:40:00Z"
}

POST /api/v1/controlling/forecasts/rolling
Authorization: Bearer bp_controlling_live_xxx
Content-Type: application/json

{
  "forecast_horizon": 12,
  "update_frequency": "monthly",
  "kpis": ["revenue", "costs", "ebitda"],
  "auto_update": true,
  "ai_model": "rolling_forecast_engine"
}

{
  "success": true,
  "rolling_forecast_id": "rf_jkl012",
  "forecast_horizon": 12,
  "update_frequency": "monthly",
  "next_update": "2025-12-01T00:00:00Z",
  "current_forecast": {
    "period": "2025-11 to 2026-10",
    "revenue": 125000000,
    "costs": 93750000,
    "ebitda": 31250000,
    "ebitda_margin": 25.0
  },
  "accuracy_trend": [
    { "month": "2025-08", "accuracy": 92.1 },
    { "month": "2025-09", "accuracy": 93.5 },
    { "month": "2025-10", "accuracy": 94.2 }
  ],
  "status": "active",
  "created_at": "2025-11-09T10:45:00Z"
}

POST /api/v1/controlling/dashboards/generate
Authorization: Bearer bp_controlling_live_xxx
Content-Type: application/json

{
  "dashboard_name": "Executive Dashboard",
  "target_audience": "C-Level",
  "kpis": ["revenue", "ebitda", "cash_flow", "working_capital"],
  "time_period": "last_12_months",
  "include_forecasts": true,
  "ai_model": "dashboard_generator"
}

{
  "success": true,
  "dashboard_id": "dash_mno345",
  "dashboard_name": "Executive Dashboard",
  "layout": {
    "widgets": [
      {
        "type": "kpi_card",
        "kpi": "revenue",
        "position": { "row": 1, "col": 1 },
        "size": "medium"
      },
      {
        "type": "trend_chart",
        "kpi": "ebitda",
        "position": { "row": 1, "col": 2 },
        "size": "medium"
      },
      {
        "type": "forecast_chart",
        "kpis": ["revenue", "ebitda"],
        "position": { "row": 2, "col": 1 },
        "size": "large"
      }
    ]
  },
  "ai_recommendations": [
    "Added revenue trend for quick performance overview",
    "Included forecast comparison for forward-looking insights",
    "Optimized layout for executive viewing"
  ],
  "created_at": "2025-11-09T10:50:00Z"
}