Integration Consent

Samoobslužný autorizačný model: postavíte URL s parametrami vašej aplikácie, používateľ ju otvorí, v KROSe schváli prepojenie a vy dostanete tokeny — buď priamym POST-om do vášho servera, alebo si ich vyzdvihnete pollingom. Žiadna dohoda s KROSom vopred nie je potrebná.

Consent URL

Základ URL je https://firma.kros.sk/integration-consent, ku ktorému pridáte nasledujúce parametre v query stringu.

https://firma.kros.sk/integration-consent
  ?plugin_name=MyEcommerceApp
  &integrator_name=Acme%20Corporation
  &version=1
  &response_mode=post
  &redirect_url=https%3A%2F%2Fmyapp.com%2Fkros%2Fcallback
  &company_mode=multiple
  &state=random-state-id-12345

Post mode

Po schválení prepojenia KROS pošle z prehliadača používateľa priamy HTTP POST na váš redirect_url, s telom vo formáte application/x-www-form-urlencoded.

Telo POST požiadavky vyzerá takto:

data[0][companyId]=123
data[0][token]=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
data[0][companyName]=Acme Corp
data[0][webhookSecret]=aG9zZXJhbmRvbXNlY3JldA==
data[1][companyId]=456
data[1][token]=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
data[1][companyName]=Tech Inc
data[1][webhookSecret]=YW5vdGhlcnNlY3JldA==
state=random-state-id-12345

state je v post mode voliteľný, ale odporúčaný — pošlite ho v consent URL a po prijatí POST-u porovnajte, či sa vrátená hodnota zhoduje s tou, ktorú ste poslali. Post mode je vhodný pre serverové webové aplikácie, ktoré majú verejne dostupný endpoint na prijatie POST-u.

Tvar tela je rovnaký v oboch režimoch company_mode. Aj pri single prídu dáta indexované — dostanete jednu položku data[0][…]. Neindexované polia companyId, token v koreni tela KROS neposiela nikdy, takže na svojej strane vystačíte s jednou vetvou kódu, ktorá prejde pole data[…] bez ohľadu na režim.

Pole data[n][webhookSecret] je v tele len vtedy, keď prepojenie má webhook; companyId, token a companyName prídu vždy. state sa pridá do tela iba vtedy, ak ste ho poslali v consent URL.

POST odošle prehliadač používateľa sám, s krátkym odpočtom po schválení. Ak sa automatické odoslanie nespustí (napr. používateľ stránku medzitým opustí), má na obrazovke tlačidlo na návrat, ktoré ten istý POST odošle ručne — váš endpoint preto musí zvládnuť aj to, že tá istá požiadavka príde s odstupom niekoľkých sekúnd či minút.

Poll mode

Po schválení prepojenia KROS tokeny neposiela nikam sám — uloží ich na svojej strane, naviazané na váš state, a to na 15 minút. Počas tohto okna si ich vyzdvihnete volaním poll endpointu.

POST /api/integration-subscription/poll HTTP/1.1
Host: api-economy.kros.sk
Content-Type: application/json

{ "state": "a7s9f8j2k1l0m3n4b5v6c7x8z9q1w2e3r4t5y6u7i8o9p0" }

Odpoveď:

{
  "data": {
    "status": "Approved",
    "companies": [
      {
        "companyId": 123,
        "companyName": "Acme Corp",
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "webHookSecret": "aG9zZXJhbmRvbXNlY3JldA=="
      }
    ]
  }
}

Zamietnutie neviete odlíšiť od čakania. Ak používateľ prepojenie neschváli, KROS si pod vaším state nič neuloží a poll endpoint bude naďalej vracať Pending — rovnako ako keby používateľ obrazovku ešte len mal otvorenú. Pollovanie preto ukončite vlastným časovým limitom (rozumné je držať sa 15-minútového okna) a po jeho uplynutí považujte pokus za neúspešný.

Na rozdiel od post mode je state v poll mode povinný — je to kľúč, pod ktorým si tokeny vyzdvihnete, takže bez neho poll endpoint nemá čo hľadať. Poll mode je vhodný pre mobilné aplikácie, SPA, CLI nástroje a background joby, teda klientov bez verejne dostupného servera na prijatie POST-u.

Životnosť a revokácia tokenu

Token získaný cez Integration Consent nemá časovú expiráciu. Neobnovuje sa a nerotuje — platí, kým prepojenie v KROSe existuje. Nepotrebujete teda refresh token ani plánované preberanie nového tokenu; potrebujete ale ošetriť, že token môže kedykoľvek prestať platiť rozhodnutím používateľa.

Prepojenia vytvorené cez consent sa používateľovi zobrazia v nastaveniach firmy v sekcii API prepojenia, v tom istom zozname ako manuálne vytvorené prepojenia. Tam ich vie aj zrušiť:

• Zmazanie prepojenia — token prestane platiť a API na ďalšie volania odpovie 401 Unauthorized.
• Reset (vygenerovanie nového tokenu) pre to isté prepojenie — nový token nahradí starý a predchádzajúci prestane platiť. Pre jedno prepojenie je vždy platný práve jeden token.

Zmena sa nemusí prejaviť v tej istej sekunde — autorizácia tokenu je na strane API krátko cachovaná, takže rátajte s rádovo minútovým oneskorením, kým zrušený token začne vracať 401.

Ďalší krok

Nastavte si príjem udalostí na Webhookoch, alebo pokračujte na Najčastejšie integrácie.