Relace a vyúčtování (REST API)¶

Tato stránka popisuje části REST API, ze kterých se skládá panel aktivní relace: náhled vyúčtování, pole active_session na dashboardu a stav zařízení. Všechny endpointy vyžadují přihlášeného uživatele (PocketBase auth token).

Jedno vyúčtování pro náhled i skutečný konec¶

Cena, kterou vidíte během relace, a částka, kterou systém při ukončení skutečně účtuje, jsou počítány jednou a toutéž funkcí (session.ComputeSettlement). Náhled ji spustí nad ještě běžící relací „jako by skončila právě teď“ a výsledek zahodí; EndSession ji spustí a výsledek zapíše. Proto náhled zahrnuje všechno, co skutečné ukončení:

• ceník zóny (sazby, přechody mezi sazbami, volné minuty) a ceny zařízení — i zařízení, které je v tu chvíli ještě zapnuté (účtuje se do okamžiku ukončení),
• slevy a pokrytí produkty (procentní sleva, permanentka, minutová kvóta, věrnostní program, balíček vstupů, sleva na zařízení),
• administrátora (vše zdarma),
• vstupní zóny: vstupné zaplacené při zahájení (prepaid) a případně doplatek za zařízení, allow_debt,
• rozdělení na úhradu z kreditu a dluh.

Náhled je čistě čtecí: nic nezapisuje (relace, položky vyúčtování, stav produktů, kredit, action logy zůstanou beze změny), neposílá příkazy zařízením a nespouští vedlejší efekty produktů (např. načítání odehraných minut věrnostního programu — ty proběhnou právě jednou, až při skutečném ukončení). Lze ho volat opakovaně.

Částka se počítá k okamžiku volání; mezi náhledem a potvrzením ukončení uplyne několik sekund, o které se výsledek může lišit.

GET /api/v1/sessions/{id}/settlement-preview¶

Vrátí vyúčtování, které by teď nastalo při ukončení relace. Pouze vlastník relace a pouze aktivní relace.

Odpověď (200):

{
  "items": [
    { "kind": "charge", "label": "Rate 10:00-10:30 (30 min)", "label_key": "zone_rate_range",
      "label_params": { "from": "10:00", "to": "10:30", "minutes": 30 }, "amount": 60 },
    { "kind": "discount", "label": "Discount (20% Sleva)", "label_key": "discount_product_named",
      "label_params": { "product": "20% Sleva" }, "amount": 12 },
    { "kind": "payment", "label": "Credit", "label_key": "credit_payment", "label_params": {}, "amount": 48 }
  ],
  "total_price": 60,
  "discount": 12,
  "rounding": 0,
  "final_price": 48,
  "prepaid": 0,
  "prepaid_price": 0,
  "amount_due": 48,
  "from_credit": 48,
  "to_debt": 0,
  "coverage": "none",
  "coverage_name": null
}

Cena a dlužná částka u uložené relace¶

U uložených (ukončených) relací mají peněžní pole tento význam:

Platí identity: total_price − discount + price_rounding = final_price, součet řádků session_price_items (bez úhrad) + price_rounding = final_price a final_price − součet úhrad = amount_due.

Klíč rounding obsahují odpovědi vyúčtování (settlement-preview, end-session, terminálový odchod); relace vrácené jako záznamy (statistiky, recent_sessions na dashboardu, admin endpointy relací, PocketBase kolekce sessions) používají název pole price_rounding.

amount_due vrací odpovědi end-session (POST /api/v1/sessions/{id}/end), GET /api/v1/sessions/{id}/qr (částka QR/SPD), dashboard (recent_sessions), statistiky, terminálový odchod a admin endpointy relací vedle final_price. Tento amount_due je stav po ukončení; amount_due v settlement-preview výše je naproti tomu částka, kterou by ukončení teprve vypořádalo.

GET /api/v1/me/dashboard — active_session¶

Při aktivní relaci obsahuje active_session (jinak je active_session null):

device_states¶

"device_states": {
  "<device_id>": {
    "state": "on",
    "confirmed": true,
    "last_command": "on",
    "last_command_at": "2026-10-07 18:02:11.000Z"
  }
}

Klíče jsou všechna zařízení zóny aktivní relace. Dotazy na stav běží souběžně, každý s limitem 2 s; výsledek se na 3 s cachuje po zařízení a po úspěšném příkazu (POST /api/v1/sessions/{id}/devices/{deviceId}/control) se cache daného zařízení zahodí, takže následné obnovení dashboardu vrací čerstvý stav. Chyba nebo timeout zařízení nikdy neshodí dashboard — zařízení se pouze ohlásí jako unknown / confirmed: false.

GET /api/v1/sessions/{id}/timeline¶

Události zařízení relace seřazené podle času (vlastník relace nebo admin):

{
  "events": [
    {
      "timestamp": "2026-10-08T08:34:00Z",
      "device_name": "Světla",
      "device_type": "light",
      "action": "off",
      "triggered_by": "user",
      "status": "failed",
      "failure_reason": "timeout",
      "error_detail": "http request failed: context deadline exceeded"
    }
  ]
}

failed záznamy se do ceny nepočítají (jediný filtr: actionlog.Billable v pricing enginu); not_sent ano. GET /api/v1/me/dashboard vrací v active_session.action_logs[] navíc pole status (stejná normalizace).