API PSB od eConnect používa OAuth 2.0 na autentifikáciu. Každá API požiadavka obsahuje Bearer token, ktorý získate z Identity Server eConnect. Tento token je platný jednu hodinu a obsahuje všetky informácie, ktoré PSB potrebuje na určenie toho, kto ste, v mene akej organizácie pracujete a čo máte povolené robiť.

V tomto článku prejdete celým procesom autentifikácie: od pochopenia autentifikačného modelu po žiadanie a používanie tokenov.

PSB pracuje so štyrmi vrstvami identifikácie. Každá vrstva odpovedá na inú otázku a spoločne určujú prístup k API.

Vrstva 1: Aplikácia (clientId + clientSecret) Identifikuje softvér, ktorý sa pripája k PSB. Softvérový partner spravidla používa jedinú sadu clientId/clientSecret pre všetkých svojich koncových zákazníkov. To zjednodušuje onboarding: koncoví zákazníci musia vyplniť menej technických údajov a pravdepodobnosť konfiguračných chýb je menšia. Všetky clientId majú rovnaký scope (ap), a teda rovnaké funkčné oprávnenia.

Vrstva 2: Koncový zákazník (username + password) Identifikuje, v mene akej organizácie sa pracuje. Pre každého koncového zákazníka eConnect vytvorí PSB používateľský účet prepojený s jedným alebo viacerými partyId (číslo obchodnej komory, DIČ, OIN, belgické číslo podniku). Pri toku Resource Owner Password Credentials zadáte username a password. UserId za týmto username určuje, ku ktorým party máte prístup; heslo iba preukazuje túto identitu. Pri toku Client Credentials určuje kontext clientId, nie používateľské heslo. Používateľské meno a heslo sa zvyčajne poskytujú priamo koncovému zákazníkovi; koncový zákazník ich potom sám zdieľa s dodávateľom softvéru. Pri vytváraní používateľského účtu koncového zákazníka v rámci vlastného PSB tenantu (napríklad pre integráciu 4PS Business Central) nesmie heslo obsahovať špeciálne znaky, s výnimkou výkričníka (!).

Vrstva 3: Prostredie (tenantId) Poskytuje administratívne oddelenie medzi prostrediami. Každý koncový zákazník zvyčajne dostane vlastný tenant, čo zaručuje úplné oddelenie správ, konfigurácie a logovania. Niektorí softvéroví partneri umiestňujú viacerých koncových zákazníkov do jedného tenantu na centrálnu správu; iní volia samostatný tenant pre každého zákazníka pre maximálnu izoláciu. Tenanty sa nedajú zlúčiť, ale používateľské účty sa dajú upraviť alebo rozšíriť.

Vrstva 4: Logovanie (subscription key, legacy) Header Ocp-Apim-Subscription-Key bol pôvodne určený na identifikáciu v log súboroch API. Na väčšine endpointov PSB tento header už nie je povinný. Ak ho pošlete, hodnota musí byť platná. eConnect niekedy stále vydáva subscription key, pretože umožňujú sledovanie každej požiadavky v logoch ku konkrétnemu softvérovému partnerovi. Poznámka: na platforme Collabrr a na niektorých legacy endpointoch je Ocp-Apim-Subscription-Key stále povinný.

Token sa žiada odoslaním POST požiadavky na endpoint /connect/token Identity Servera.

Toto je odporúčaný tok pre integrácie server-server. Odošlete iba svoj clientId a clientSecret.

POST /connect/token HTTP/1.1
Host: identity.econnect.eu
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=vas-client-id
&client_secret=vas-client-secret
&scope=ap

Pri tomto toku zadáte aj používateľské meno a heslo. Je to užitočné, keď sú oprávnenia viazané na konkrétneho koncového používateľa.

POST /connect/token HTTP/1.1
Host: identity.econnect.eu
Content-Type: application/x-www-form-urlencoded

grant_type=password
&client_id=vas-client-id
&client_secret=vas-client-secret
&username=vase-meno-pouzivatela
&password=vase-heslo
&scope=ap

Pri úspešnej požiadavke dostanete JSON objekt obsahujúci access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "ap"
}

Pole expires_in udáva, koľko sekúnd je token platný. Predvolená hodnota je 3600 sekúnd (1 hodina).

Token Bearer zahrňte do headera Authorization pri každej API požiadavke na PSB:

GET /api/v1/me HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

PSB validuje token pri každej požiadavke. Ak je token neplatný alebo vypršaný, dostanete odpoveď 401 Unauthorized.

Bearer token je platný 3600 sekúnd. Po vypršaní musíte požiadať o nový token cez ten istý endpoint /connect/token. Neexistuje samostatný refresh tok: jednoducho zopakujete žiadosť o token.

V praxi je najlepšie požiadať o nový token krátko pred vypršaním aktuálneho, napríklad po 3500 sekundách. Tým sa zabráni zlyhaniu API volania kvôli vypršanému tokenu, kým je požiadavka na ceste.

1. Token vyžiadaný              → platný do t+3600s
2. Po ~3500s: nový token        → starý token ešte ~100s platný
3. Prepnutie na nový token

Token uložte vo Vašej aplikácii a používajte ho pre viacero požiadaviek. Nežiadajte nový token pri každom API volaní, pretože to zbytočne zaťažuje Identity Server.

Štandardne softvérový partner používa jednu sadu clientId/clientSecret pre všetkých koncových zákazníkov. V niektorých situáciách je vhodné používať viacero sád:

• Oddelenie testu a produkcie. Použite samostatný clientId pre akceptačné prostredie (accp-identity.econnect.eu) a pre produkciu (identity.econnect.eu). Tým sa zabráni náhodnému použitiu testovacích údajov v produkcii.
• On-premise inštalácie. Ak softvér beží u koncového zákazníka a zákazník má prístup ku konfigurácii, zdieľaný clientSecret môže predstavovať bezpečnostné riziko. So samostatným clientId na zákazníka sa obmedzí škoda v prípade úniku prihlasovacích údajov.
• Oddelené oprávnenia na integráciu. Ak budujete viacero samostatných aplikácií, z ktorých každá potrebuje inú API funkcionalitu (napríklad fakturačný modul a modul objednávok), môžete pre každú aplikáciu použiť vlastný clientId iba s potrebnými oprávneniami.

Zrušenie clientSecret sa týka iba prislúchajúceho clientId. Ostatní zákazníci alebo integrácie nie sú dotknutí.

Ak dostanete 401 pri API volaní na PSB, najprv skontrolujte, či je token ešte platný. Vo väčšine prípadov vypršal a stačí vyžiadať nový token.

Nasledujúci diagram ukazuje, ako aplikácia vyžiada token z Identity Servera a potom tento token použije na volanie API PSB.

Kompletná API referencia vrátane všetkých endpointov a formátov požiadaviek/odpovedí je k dispozícii v interaktívnej Swagger dokumentácii.