Dokumentácia

API Reference — SScloud v1

SScloud poskytuje REST API pre integráciu s mobilnými aplikáciami a externými systémami.

Autentifikácia

API vyžaduje Bearer token (Laravel Sanctum). Token získate od administrátora.

Authorization: Bearer {your-api-token}

Endpointy

Zoznam elektrární

GET /api/v1/plants

Vráti zoznam všetkých elektrární prístupných pre autentifikovaného používateľa.

Každá elektráreň obsahuje:

Aktuálny výkon (kW)
Dennú výrobu (kWh)
Celkovú výrobu (kWh)
Stav licencie
Typ meniča (Huawei, Deye, SolarEdge, GoodWe, Growatt, Sungrow)

Detail elektrárne

GET /api/v1/plants/{id}

Podrobné informácie o elektrárni vrátane zoznamu zariadení (meniče, batérie, smart metre).

Historické dáta

GET /api/v1/plants/{id}/history

Historické snapshoty v 5-minútovom intervale.

Parametre:

days — počet dní (1-90, predvolené: 7)
limit — max počet záznamov (1-500, predvolené: 288)

Energetická bilancia

GET /api/v1/plants/{id}/energy

Denná agregácia energetických dát.

Parametre:

days — počet dní (1-365, predvolené: 30)

Portfólio prehľad

GET /api/v1/portfolio

Súhrnné štatistiky naprieč všetkými vašimi elektrárňami.

Odpoveď obsahuje:

Celkový počet elektrární, kapacita (kWp)
Aktuálny celkový výkon (kW) a denná výroba (kWh)
Špecifický výnos (kWh/kWp)
Stav elektrární (vyrába / online / neaktuálne / offline)
Rozdelenie podľa značky meniča
Počet licencovaných / nelicencovaných elektrární

Počasie a predikcia výroby

GET /api/v1/plants/{id}/weather

Aktuálne počasie a odhad dennej výroby pre elektráreň.

Vyžaduje: GPS súradnice v nastaveniach elektrárne.

Odpoveď obsahuje:

Teplota, oblačnosť, slnečné žiarenie
Podmienky (výborné / dobré / stredné / slabé)
Odhad dennej výroby na základe žiarenia a kapacity

Health Check

GET /api/health (verejný, bez autentifikácie)

Kontrola stavu API. Vráti:

{
  "status": "ok",
  "timestamp": "2026-03-19T18:00:00Z",
  "version": "2.0.0"
}

Webhooky

SScloud môže posielať webhookové udalosti na váš endpoint. Konfigurácia v časti Webhooky v administrácii.

Typy udalostí

| Udalosť | Popis |

|---------|-------|

| plant.offline | Elektráreň je offline (žiadne dáta >60 min) |

| plant.low_production | Nízka výroba oproti očakávaniu |

| plant.fuse_alert | Prúdový nadprúd na poistke |

| plant.snapshot | Nový snapshot bol zaznamenaný |

| report.monthly | Mesačný report bol vygenerovaný |

| license.expiring | Licencia expiruje do 30 dní |

Bezpečnosť

Každý webhook je podpísaný pomocou HMAC-SHA256. Overujte podpis v headeri X-SScloud-Signature.

$isValid = hash_equals(
    hash_hmac('sha256', $payload, $webhookSecret),
    $request->header('X-SScloud-Signature')
);

Status badge (verejný)

GET /api/badge/{plant_id}?token={badge_token}

Vráti SVG obrázok (shields.io štýl) s aktuálnym stavom elektrárne. Nevyžaduje Sanctum token — autentifikácia prebieha cez badge_token v query parametri.

Farby podľa stavu:

🟢 Zelená — vyrába (zobrazuje aktuálny výkon v kW)
🔵 Modrá — online (0 kW)
🟡 Žltá — neaktuálne dáta
🔴 Červená — offline

Použitie na webstránke:

<img src="https://cloud.supersolar.sk/api/badge/1?token=VÁŠ_TOKEN" alt="Stav elektrárne">

Badge token nájdete v nastaveniach elektrárne (/plants/{id}/settings).

Rate limit: 120 požiadaviek za minútu.

GET /api/v1/plants/{id}/maintenance

Servisný denník elektrárne — história údržby.

Parametre:

limit — max záznamov (predvolené 50, max 100)

Odpoveď:

{
  "plant_id": 1,
  "plant_name": "FVE Rodinný dom",
  "total_entries": 5,
  "total_cost_eur": 450.00,
  "entries": [
    {
      "id": 1,
      "type": "cleaning",
      "type_label": "Čistenie",
      "title": "Ročné čistenie panelov",
      "description": "Vyčistené všetky panely...",
      "performed_at": "2026-03-15",
      "cost_eur": 150.00,
      "technician": "Ján Novák",
      "logged_by": "admin",
      "created_at": "2026-03-15T14:00:00+01:00"
    }
  ]
}

Chybové kódy

| Kód | Popis |

|-----|-------|

| 401 | Neautentifikovaný |

| 403 | Nemáte prístup |

| 404 | Elektráreň nenájdená |

| 500 | Interná chyba |

Rate Limiting

60 požiadaviek za minútu per token.