====== Balans Web API - Console ======

Administratorska veb konzola za registraciju klijenata i upravljanje licencama modula nad Balans Web API-jem.\\\\
Zamenjuje ručni rad kroz Swagger — firma → nalog → moduli → licence — kroz forme, sa generisanim licencama kao spiskom kodova.

Konzola je zaseban frontend koji komunicira isključivo kroz REST zahteve modula [[kb:web_api:module_realm|Realm]]. Nema sopstvenu bazu ni servis: posle build-a je statička aplikacija koju servira veb server.

===== Pristup =====

Svi administratorski zahtevi traže ulogu **ADMIN** (profil ''MelanyAdmin'') i registrovan modul **Realm**.\\\\
Prijava ide kroz ''POST /api/rest/auth'', a dobijeni token se šalje u zaglavlju:
<code>
\\
Authorization: Bearer {token}\\

</code>

Prijava prima **pubId** firme (''wcom.pubid''), ne ''firid''.

===== REST API Zahtevi =====

^ Metod ^ Putanja ^ Uloga ^ Opis ^ Revizija ^
| GET | /api/rest/realm/admin/companies | ADMIN | Spisak registrovanih firmi | 26-08-24 |\\
| GET | /api/rest/realm/admin/company/{firid}/modules | ADMIN | Aktivni moduli firme sa licencom i datumom isteka | 26-08-24 |\\
| GET | /api/rest/realm/admin/licences | ADMIN | Spisak licenci po modulu, firmi i statusu | 26-08-24 |\\
| POST | /api/rest/realm/admin/licence/assign | ADMIN | Dodela slobodne licence ciljnoj firmi | 26-08-24 |\\
| POST | /api/rest/realm/admin/licence/revoke | ADMIN | Odvezivanje licence od firme | 26-08-24 |\\
| PUT | /api/rest/realm/admin/licence | ADMIN | Izmena trajanja licence | 26-08-24 |

===== Ulazni parametri =====

==== Spisak licenci ====

''GET /api/rest/realm/admin/licences'' prima tri opciona URL parametra:

* **moduleId** - filter po modulu (0 ili izostavljen = svi moduli)\\
* **companyId** - filter po firmi, vrednost je ''firid'' (izostavljen = sve firme)\\
* **free** - ''true'' = slobodne, ''false'' = iskorišćene, izostavljen = sve

==== Akcije nad licencom ====

Telo zahteva je JSON:
<code>
\\
POST /api/rest/realm/admin/licence/assign\\
{ "licence": "4301-KUY0YI", "firid": 223 }

POST /api/rest/realm/admin/licence/revoke\\
{ "licence": "4301-KUY0YI" }

PUT /api/rest/realm/admin/licence\\
{ "licence": "4301-KUY0YI", "duration": 30 }\\

</code>

^ Polje ^ Tip ^ Opis ^
| licence | string | Kod licence (''walibslic.walic_licence'') |\\
| firid | integer | Identifikator ciljne firme (''firme.firid''), samo pri dodeli |\\
| duration | integer | Trajanje u danima; **0 = neograničeno** (istek 3000-01-01) |

===== Životni ciklus licence =====

Licenca je kod za jedan modul, jednu firmu i određeno trajanje. Dva odvojena koraka:

- **Generisanje** (''PUT /api/rest/realm/licence/generate'') pravi slobodne kodove, nevezane za firmu.\\
- **Dodela** veže kod za firmu i upisuje aktivan modul sa datumom isteka.

Odvezivanje vraća kod među slobodne i postavlja istek aktivnog modula na prethodni dan — zapis o modulu se **ne briše**, čime se čuvaju podešavanja modula.\\\\
Premeštanje licence sa jedne firme na drugu je zato dva koraka: odvezivanje pa dodela.

===== Registracija klijenta =====

^ Korak ^ Zahtev ^ Uloga ^ Opis ^ Revizija ^\\
| 1 | POST /api/rest/realm/company | bez tokena | Registracija firme; vraća ''pubId'' | 26-08-24 |\\
| 2 | POST /api/rest/realm/user | bez tokena | Klijentski nalog za ''pubId'' firme | 26-08-24 |\\
| 3 | POST /api/rest/realm/licence/activate | USER, ADMIN | Aktivacija licence za modul | 26-08-24 |\\
| 4 | PUT /api/rest/realm/licence/generate | ADMIN | Generisanje licenci za modul | 26-08-24 |

Korak 1 je idempotentan — ponovna registracija iste firme vraća postojeći ''pubId'', ne grešku.\\\\
Firma mora prethodno da postoji u tabeli ''firme'' (''firid'' se ne kreira kroz konzolu).

===== Rezultat =====

^ HTTP Kod ^ Opis ^ Revizija ^\\
| 200 | Zahtev je uspešno izvršen. | 26-08-24 |\\
| 400 | Nije predat obavezan parametar (''firid'', ''duration'' ili ''licence''). | 26-08-24 |\\
| 401 | Token nije validan. | 26-08-24 |\\
| 403 | Nalog nema ulogu ADMIN ili nema pristup modulu Realm. | 26-08-24 |\\
| 404 | Licenca ili firma ne postoji. | 26-08-24 |\\
| 409 | Licenca je već dodeljena — prvo je odvezati. | 26-08-24 |\\
| 409 | Firma već ima važeću licencu za taj modul. | 26-08-24 |\\
| 409 | Modul koristi besplatno licenciranje — dodela nije primenljiva. | 26-08-24 |\\
| 409 | Licenca nije dodeljena — nema šta da se odveže. | 26-08-24 |\\
| 409 | Modul je neaktivan ili u režimu održavanja. | 26-08-24 |\\
| 500 | Nepoznata serverska greška. | 26-08-24 |

===== Napomene =====

* **pubId i firid nisu isto.** ''firid'' je identifikator firme u Balansu (i naziv firmine baze ''b{firid}''), a ''pubId'' generiše server pri registraciji firme i koristi se pri prijavi.\\
* **realmId** (''wcom.mel_id'') je identifikator Balans klastera na kom firma živi. Pri registraciji firme server ga proverava u registru izdatih licenci; nepoznat ''realmId'' se odbija.\\
* **Trajanje 0** znači neograničeno i prikazuje se kao datum isteka 3000-01-01.