Obchod doplnkov

Obchod doplnkov je zoznam doplnkov ponúkaných priamo v KROS aplikácii, odkiaľ si ich zákazník jedným klikom nainštaluje. Zaradenie doplnku do tohto zoznamu nie je samoobslužné — vyžaduje dohodu s KROSom a manifest, ktorý opisuje váš doplnok strojovo čitateľným spôsobom.

Ako sa doplnok dostane do obchodu

Na rozdiel od Integration Consent, ktorý si napojíte úplne samoobslužne bez akejkoľvek registrácie, zaradenie doplnku do obchodu doplnkov samoobslužné nie je. Napíšte na integracie@kros.sk a uveďte:

• názov doplnku,
• čo doplnok robí,
• na ktorý KROS produkt sa napája (napr. KROS Fakturácia, KROS Sklad),
• spôsob autentifikácie (token-broker alebo manual — pozri nižšie),
• HTTPS base URL doplnku.

Na základe toho KROS pridelí pluginId/partnerId a dohodne technické detaily zvoleného spôsobu autentifikácie. Až potom má zmysel pripravovať manifest.json a balík na nahratie.

manifest.json

manifest.json je jediný zdroj pravdy o tom, ako sa doplnok volá, čo robí, kto je jeho partner a ako sa doň prihlasuje. Má štyri povinné najvyššie objekty:

plugin.id je stabilný identifikátor doplnku, jeho stredný segment sa musí zhodovať s plugin.partnerId. plugin.changelog je pri prvej verzii null, pri každej ďalšej verzii je povinný. partner.contact musí niesť aspoň jeden kontaktný kanál — e-mail, support URL alebo vyplnené website.

Dva spôsoby autentifikácie v manifeste

Pole authentication.method je presne jedno z dvoch:

• token-broker — doplnok sa otvára vnútri KROS aplikácie a používateľ je doň automaticky prihlásený. Vyžaduje tokenBroker.baseUrl (HTTPS) a zdieľaný API kľúč. Celý protokol je popísaný na stránke Token Broker partner.
• manual — používateľa presmerujete do externého okna mimo KROS aplikácie. Vyžaduje manual.redirectUrl; nejde o inštaláciu v zmysle Token Brokera a nenesie žiadny token.

Príklad manifestu so spôsobom token-broker (skrátené o nepovinné polia):

{
  "manifestVersion": "1.0.0",
  "plugin": {
    "id": "sk.partner-id.doplnok-id",
    "partnerId": "partner-id",
    "name": "Názov doplnku",
    "version": "1.0.0",
    "changelog": null,
    "requiresReconfiguration": false
  },
  "display": {
    "shortDescription": "Krátky popis doplnku (10 – 150 znakov).",
    "categories": ["accounting"],
    "tags": ["priklad", "doplnok"],
    "detail": { "description": "## Názov doplnku\n\nMarkdown popis, 50 – 20000 znakov." }
  },
  "partner": {
    "name": "Partner s.r.o.",
    "website": "https://partner.example.com",
    "privacyPolicyUrl": "https://partner.example.com/privacy",
    "contact": { "emails": ["support@partner.example.com"] },
    "license": { "type": "proprietary", "url": "https://partner.example.com/eula" }
  },
  "authentication": {
    "method": "token-broker",
    "tokenBroker": {
      "baseUrl": "https://doplnok.partner.example.com",
      "apiKeySecretRef": "Plugins:sk.partner-id.doplnok-id:ApiKey",
      "apiKey": "VLOZ_SEM_API_KEY"
    }
  }
}

Balík

Endpoint na nahratie doplnku prijíma .zip archív, ktorý má v koreňovom adresári súbor manifest.json (a spravidla ikonu doplnku). Samotný manifest.json bez zabalenia do .zip sa nahrať nedá.