====== Dokumentace k REST API Konfigurátoru ======



Toto API poskytuje přístup ke konfigurátoru prostřednictvím několika endpointů. Podporuje operace pro získání vlastností konfigurátoru, nastavení vlastností a získání konfigurátoru na základě kódu. Je určeno primárně pro komunikaci s grafickým klientm SCbrowser na základě popisu:
{{ :orfertopen:lc:lc_api:schema_2d_konfigurator_sapeli.pdf |}}



**Use Case: Integrace 2D konfigurátoru dveří SAPELI s SCbrowserem**

**Účel:** Tento use case popisuje integraci 2D konfigurátoru dveří SAPELI s SCbrowserem, který umožňuje online překreslení dveří při změně parametrů a poskytuje různé módy zobrazení a export.

**Aktéři:**

  * **Koncový uživatel**: Osoba používající MOPS klienta na svém počítači.
  * **MOPS klient**: Desktopová aplikace u koncového uživatele.
  * **SCbrowser**: Aplikace zobrazující náhled dveří na základě parametrů.
  * **MOPS server**: Server poskytující data o sortimentu a konfiguracích dveří.
  * **SC server**: Server poskytující 2D geometrie modelů a textury.

**Předpoklady:**

  * Koncový uživatel má přístup k MOPS klientovi a SCbrowseru na svém počítači.
  * MOPS klient je schopen autentizace a vytvoření zakázky.
  * MOPS server a SC server jsou dostupné a funkční.

**Scénář:**

  - **Autentizace a přihlášení uživatele:**
    * Koncový uživatel spustí MOPS klienta.
    * MOPS klient vyžádá přihlašovací údaje a autentizuje uživatele pomocí MOPS serveru.
  - **Vytvoření zakázky:**
    * Po úspěšné autentizaci uživatel zadá údaje nové zakázky.
    * MOPS klient vytvoří zakázku a zašle změny parametrů do MOPS serveru.
  - **Spuštění SCbrowseru:**
    * Koncový uživatel spustí SCbrowser.exe.
    * SCbrowser je připraven komunikovat s MOPS klientem pomocí Win32Eventů.
  - **Změna parametrů v konfigurátoru:**
    * Uživatel změní parametry dveří v MOPS klientovi.
    * MOPS klient zašle změněné parametry do MOPS serveru, který vygeneruje data ve formátu JSON.
  - **Překreslení a aktualizace náhledu:**
    * SCbrowser obdrží Win32Event, že došlo ke změně parametrů.
    * SCbrowser zašle žádost na webovou službu MOPS serveru s ID eventu.
    * MOPS server vrátí vygenerovaná data ve formátu JSON.
    * SCbrowser načte data a aktualizuje náhled dveří podle nových parametrů.
  - **Zobrazení a export:**
    * SCbrowser zobrazí dveře v základním zobrazení.
    * Uživatel může přepnout na zobrazení kót, expertní mód, tisk nebo export do PDF.

**Alternativní scénáře:**

  * **Neplatné přihlašovací údaje:**
    * Pokud uživatel zadá neplatné přihlašovací údaje, MOPS klient zobrazí chybovou zprávu a neumožní přístup.
  * **Chyba při komunikaci s MOPS serverem:**
    * Pokud dojde k chybě při zasílání změněných parametrů do MOPS serveru, MOPS klient informuje uživatele a pokusí se o opětovné odeslání.

**Výstupy:**

  * Aktuální náhled dveří v SCbrowseru.
  * Možnost exportu konfigurace do PDF.
  * Možnost tisku konfigurace.

**Diagram sekvencí:**
<code plaintext>
Koncový uživatel -> MOPS klient: Přihlášení
MOPS klient -> MOPS server: Ověření přihlášení
MOPS server -> MOPS klient: Potvrzení přihlášení
Koncový uživatel -> MOPS klient: Zadání zakázky
MOPS klient -> MOPS server: Vytvoření zakázky
MOPS server -> MOPS klient: Potvrzení zakázky
Koncový uživatel -> SCbrowser: Spuštění
SCbrowser -> MOPS klient: Win32Event
Koncový uživatel -> MOPS klient: Změna parametrů
MOPS klient -> MOPS server: Odeslání parametrů
MOPS server -> SCbrowser: Data ve formátu JSON
SCbrowser -> Koncový uživatel: Aktualizace náhledu
</code>
===== Autentizace =====

Pro přístup k API je vyžadována autentizace. Každý požadavek musí obsahovat platný autentizační token v hlavičce. Token je získán prostřednictvím přihlašovacího procesu.

==== 1. Přihlášení ====
  * **URL:** `/auth/login`
  * **Metoda:** `POST`
  * **Formát vstupu:** `application/json`
  * **Formát výstupu:** `application/json`
  
  == Parametry: ==
    * **`username` (string)**: Login do OR-SYSTEM Open.
    * **`password` (string)**: Heslo do OR-SYSTEM Open.

  == Příklad požadavku: ==
  <code json>
  {
    "username": "uzivatel",
    "password": "tajneheslo"
  }
  </code>

  == Příklad odpovědi: ==
  <code json>
  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
  </code>

==== 2. Odhlášení ====
  * **URL:** `/auth/logout`
  * **Metoda:** `POST`
  * **Formát vstupu:** `application/json`
  * **Formát výstupu:** `application/json`
  
  == Parametry: ==
    * **`token` (string)**: Autentizační token, který má být zneplatněn.

  == Příklad požadavku: ==
  <code json>
  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
  </code>

  == Příklad odpovědi: ==
  <code json>
  {
    "status": "OK"
  }
  </code>

==== 3. Obnovení tokenu ====
  * **URL:** `/auth/refresh`
  * **Metoda:** `POST`
  * **Formát vstupu:** `application/json`
  * **Formát výstupu:** `application/json`
  
  == Parametry: ==
    * **`refreshToken` (string)**: Token pro obnovení autentizace.

  == Příklad požadavku: ==
  <code json>
  {
    "refreshToken": "dGVzdHJlZnJlc2h0b2tlbg=="
  }
  </code>

  == Příklad odpovědi: ==
  <code json>
  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "dGVzdHJlZnJlc2h0b2tlbg=="
  }
  </code>


===== Endpointy =====

====1. Získání konfigurátoru====
Tento endpoint lze využít nezávisle na aplikaci SCbrowser. Po zadání kódu konfigurátoru, se získá seznam vlastností a popis konfigurátoru.
SCbrowser si tyto hodnoty uloží a v dalších krocích pak pracuje s odkazy.

  * **URL:** `/konfigurator/get_konfigurator`
  * **Metoda:** `GET`
  * **Formát vstupu:** `application/json`
  * **Formát výstupu:** `application/json`
  
== Parametry: ==
  * **`kodKonfiguratoru` (string)**: Kód konfigurátoru, který má být získán.

== Příklad požadavku: ==
<code json>
{
  "kodKonfiguratoru": "V300"
}
</code>

== Příklad odpovědi: ==
<code json>
{
  "cKonfiguratorVlastnostExports": [
    {
      "cKonfiguratorSadaExports": [
        {
          "cKonfiguratorHodnotas": [
            {
              "idpk": 42515733,
              "kgsIdpk": 88069,
              "hodnota": "MAX 0529 SG",
              "kgnJn": "N"
            },
            {
              "idpk": 42875093,
              "kgsIdpk": 88069,
              "hodnota": "F095-ST87",
              "kgnJn": "N"
            },
            {
              "idpk": 42796385,
              "kgsIdpk": 88069,
              "hodnota": "S 1005-Y10R",
              "kgnJn": "N"
            },
            {
              "idpk": 42797942,
              "kgsIdpk": 88069,
              "hodnota": "S 8505-B80G",
              "kgnJn": "N"
            },
            {
              "idpk": 42797061,
              "kgsIdpk": 88069,
              "hodnota": "S 2502-B",
              "kgnJn": "N"
            },
            {
              "idpk": 42515729,
              "kgsIdpk": 88069,
              "hodnota": "MAX 0502 MT",
              "kgnJn": "N"
            },
            {
              "idpk": 42797121,
              "kgsIdpk": 88069,
              "hodnota": "S 3010-Y10R",
              "kgnJn": "N"
            },
            {
              "idpk": 42797674,
              "kgsIdpk": 88069,
              "hodnota": "S 5040-G",
              "kgnJn": "N"
            },
            {
              "idpk": 42796743,
              "kgsIdpk": 88069,
              "hodnota": "S 1515-R90B",
              "kgnJn": "N"
            },
            {
              "idpk": 42797713,
              "kgsIdpk": 88069,
              "hodnota": "S 5540-B30G",
              "kgnJn": "N"
            },
            {
              "idpk": 41760882,
              "kgsIdpk": 88069,
              "hodnota": "POL C 047-FA",
              "kgnJn": "N"
            },
            {
              "idpk": 42577856,
              "kgsIdpk": 88069,
              "hodnota": "POL U 192-EXM",
              "kgnJn": "N"
            },
            {
              "idpk": 42796145,
              "kgsIdpk": 88069,
              "hodnota": "S 0520-B40G",
              "kgnJn": "N"
            },
            {
              "idpk": 43792167,
              "kgsIdpk": 88069,
              "hodnota": "H3317-ST28",
              "kgnJn": "N"
            }
 ],
          "idpk": 88073,
          "kgvIdpk": 3031,
          "kod": "9999999999",
          "stav": 0,
          "nazev": "systémová",
          "popis": "                                                            ",
          "vksIdpk": 25225,
          "ename": "klima   ",
          "edat": 20120425,
          "def": "N",
          "zmenaCis": 0,
          "zmenaTyp": " ",
          "typ": "B",
          "typVyr": " ",
          "kgqJn": "N",
          "expJn": " ",
          "aname": "        ",
          "adat": "Jan 1, 1900, 12:00:00 AM",
          "iko": "KGS,88073"
        }
      ],
      "idpk": 3031,
      "kgzIdpk": 112,
      "pos": 80,
      "stav": 0,
      "typ": " ",
      "por": 80,
      "vkvIdpk": 713,
      "vkzIdpk": 433,
      "nazev": "Šířka",
      "popis": "                                                            ",
      "vlivIna": "N",
      "inaOd": 0,
      "inaDel": 0,
      "vlivNaz": "N",
      "nazOd": 0,
      "nazDel": 0,
      "vlivVar": "N",
      "varOd": 0,
      "varDel": 0,
      "editJn": "N",
      "algTyp": " ",
      "pocSad": 1,
      "ename": "klima   ",
      "edat": 20120425,
      "typK": "N",
      "vlivOzn1": "N",
      "ozn1Od": 0,
      "ozn1Del": 0,
      "vlivOzn2": "N",
      "ozn2Od": 0,
      "ozn2Del": 0,
      "format": "X20       ",
      "an": "A",
      "hal": 20,
      "hnk": 0,
      "pilJn": "N",
      "defTsJn": "N",
      "aJn": "N",
      "vlV": "N",
      "vlH": "N",
      "kf": 0,
      "exK": 0,
      "hodMin": "                    ",
      "hodMax": "                    ",
      "nasob": "N",
      "pismo": "N",
      "testLim": " ",
      "povJn": "J",
      "defJn": "N",
      "zmenaCis": 0,
      "zmenaTyp": " ",
      "prHl": "N",
      "defImp": "N",
      "kgnJn": "N",
      "eshopJn": "N",
      "mecNr": 0,
      "tKgs": "B",
      "kMkz": 6029,
      "aname": "klima   ",
      "adat": "Apr 25, 2012, 11:12:14 AM",
      "rPos": 0,
      "nHodnota": "                    ",
      "dObr": " ",
      "lObr": " ",
      "oTyp": " ",
      "kSmc": 3915,
      "cVlivVlastnost": {
        "kgvIdpk": 3031,
        "stav": 0,
        "vliv01": "J",
        "vliv02": "N",
        "vliv03": "N",
        "vliv04": "N",
        "vliv05": "N",
        "vliv06": "N",
        "vliv07": "N",
        "vliv08": "N",
        "vliv09": "N",
        "vliv10": "N",
        "vliv11": "N",
        "vliv12": "N",
        "vliv13": "N",
        "vliv14": "N",
        "vliv15": "N",
        "vliv16": "N",
        "vliv17": "N",
        "vliv18": "N",
        "vliv19": "N",
        "vliv20": "N",
        "ename": "klima   ",
        "edat": 20120425,
        "aname": "        ",
        "adat": "Jan 1, 1900, 12:00:00 AM"
      },
      "iko": "KGV,3031"
    }
  ],
  "kod": "V300                          ",
  "stav": 5,
  "idpk": 112,
  "nazev": "V_Obkladový systém                      ",
  "popis": "V_Obkladový systém                                          ",
  "typ": "3",
  "ename": "klima   ",
  "edat": 20120425,
  "inaDel": 12,
  "nazDel": 40,
  "varDel": 30,
  "ozn1Del": 30,
  "ozn2Del": 30,
  "doplV": "N",
  "minPor": 0,
  "maxPor": 999999,
  "aktPor": 706,
  "novy": "1",
  "cenaJn": "M",
  "defJn": "J",
  "kgqJn": "N",
  "zmenaJn": "N",
  "zmenaCis": 0,
  "hlD": "N",
  "urceni": " ",
  "cenMkz": 6464,
  "aname": "linhova2",
  "adat": "May 10, 2024, 4:05:36 PM",
  "dObr": " ",
  "lObr": " ",
  "oKfgJn": " ",
  "oKfgMkz": 0,
  "cenSmc": 4441,
  "oKfgSmc": 0,
  "cSabKfg": {
    "kgzIdpk": 112,
    "stav": 0,
    "inaR": "VD300-                        ",
    "nazR": "                                        ",
    "varR": "V300                          ",
    "ename": "klima   ",
    "edat": 20120425,
    "ozn1R": "                              ",
    "ozn2R": "                              ",
    "aname": "klima   ",
    "adat": "Apr 25, 2012, 9:50:06 AM"
  },
  "iko": "KGZ,112"
}</code>


====2. Získání vlastností konfigurátoru====
Získání možných kombinací vlastností v daném kroku konfigurace na základě requestId. Tento endpointje určen pro komunikaci s aplikací SCbrowser.

  * **URL:** `/konfigurator/get_properties`
  * **Metoda:** `GET`
  * **Formát vstupu:** `application/json`
  * **Formát výstupu:** `application/json`
  
== Parametry: ==
  * **`requestId` (integer)**: ID požadavku na získání vlastností.

== Příklad požadavku: ==
<code json>
{
  "requestId": 123
}
</code>

== Příklad odpovědi: ==
<code json>
{
"99":"99",
"A":"B",
"HNormal":"K41167875",
"H---":"K42548837",
"H1970":"K41171997",
"HČeská":"K41171800",
"H10":"K41169333",
"H140 mm":"K41171276",
"HO3":"K41184219",
"Hbez":"K41189148",
"HLevé":"K41171795",
"HStandardní SATÉN":"K41178641",
"H600":"K41171004",
"HStandardní":"K41167772",
"HUpraveno":"K41186633",
"HByt.s polodr.dř.zár.":"K41312159",
"HCPL Dub 17 struktur":"K42423206",
"HJednokřídlové":"K41167888",
"H65 mm":"K41189122",
"HDveře+zárubeň":"K41167713",
"H80/10 SATÉN":"K41172161",
"HElegant Komfort":"K42120310",
"HV100-VD":"K41167706",
"HKOMFORT WC":"K42120396"
}
</code>

====2. Nastavení vlastností konfigurátoru====
Tento endpointje určen pro komunikaci s aplikací SCbrowser. Aktualizje změněné vlastnosti v grafické konfiguraci do OR-SYSTEMu.
  * **URL:** `/konfigurator/set_properties`
  * **Metoda:** `POST`
  * **Formát vstupu:** `application/json`
  * **Formát výstupu:** `application/json`
  
== Parametry: ==
  * **`requestId` (integer)**: ID požadavku na nastavení vlastností.

== Příklad požadavku: ==
<code json>
{
  "requestId": 123
}
</code>

== Příklad odpovědi: ==
<code>
OK: {"message":"","status":200}
</code>


====Výjimky a chyby====
V případě chyb nebo výjimek API vrací chybové zprávy s popisem problému.

== Příklad chybové odpovědi: ==
<code>
ERROR: {"message":"nenalezen kod V3100","status":500}
</code>