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

KROS potrebujete na dvoch miestach — na začiatku, aby vám doplnok zaregistroval, a na konci, aby ho zverejnil. Všetko medzi tým, teda príprava balíka aj jeho testovanie, je vo vašich rukách a nikoho sa na to nemusíte pýtať.

1. Registrácia doplnku

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í plugin.id a partnerId, dohodne technické detaily zvoleného spôsobu autentifikácie a sprístupní vám v module Doplnky tlačidlo na nahranie balíka. Až potom má zmysel pripravovať manifest.json a balík.

2. Príprava a testovanie

Balík si zložíte podľa pravidiel na tejto stránke a nahráte ho sami tým tlačidlom v module Doplnky. Hneď uvidíte, či prešel validáciou, aj to, ako sa doplnok zákazníkovi zobrazí. Nahrávať môžete opakovane, kým nebudete s výsledkom spokojní — nahraný doplnok nie je verejný, kým ho KROS nezverejní.

Chyby v manifeste teda odhalíte sami a v priebehu sekúnd; nič neposielate e-mailom a na nikoho nečakáte. Aj tak sa vyplatí prejsť si kontrolu pred nahratím na konci tejto stránky — ušetrí vám to kolá.

3. Schválenie a zverejnenie

Keď je doplnok hotový, napíšte KROSu, aby ho schválil. Schválením sa doplnok zaradí do obchodu doplnkov a stane sa verejne dostupným pre zákazníkov.

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. Okrem povinného poľa manifestVersion (vždy "1.0.0" — je to verzia schémy, nie verzia vášho doplnku) má štyri povinné najvyššie objekty:

Referencia polí

Toto je úplný zoznam polí a ich limitov. Dĺžky sa merajú po odstrihnutí okrajových medzier a takto odstrihnutá hodnota sa aj ukladá. Všetky URL musia byť https — jediná výnimka je manual.redirectUrl, ktoré pripúšťa aj http.

plugin

display

partner

partner.contact

Objekt contact je povinný, ale všetky jeho zoznamy sú jednotlivo nepovinné — platí len jedno spoločné pravidlo: musí byť vyplnený aspoň jeden kontaktný kanál, čiže aspoň jeden emails, alebo aspoň jeden supportUrls, alebo neprázdne partner.website. Každý zoznam, ktorý uvediete, má 1 – 3 položky bez duplicít.

partner.license

Dva spôsoby autentifikácie

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ý. Celý protokol je popísaný na stránke Token Broker partner.
• manual — používateľa presmerujete do externého okna mimo KROS aplikácie. Nejde o inštaláciu v zmysle Token Brokera a nenesie žiadny token.

Objekty tokenBroker a manual sa navzájom vylučujú: ten, ktorý zvolenému method nepatrí, musí byť null alebo úplne chýbať. Vyplniť oba je chyba.

Povolené hodnoty

Tri polia v manifeste prijímajú len presne vymenované hodnoty. Zapisujú sa malými písmenami so spojovníkmi a iná podoba tej istej hodnoty prejsť nemusí.

display.categories

partner.license.type

Príklady manifestu

Prvý príklad používa token-broker, druhý manual. Oba sú kompletné a platné — nepovinné polia sú v nich vyplnené, aby bolo vidieť ich tvar.

{
  "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", "reporting"],
    "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"],
      "phones": ["+421 900 000 000"],
      "supportUrls": ["https://partner.example.com/support"],
      "documentationUrls": ["https://partner.example.com/docs"]
    },
    "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"
    }
  }
}

{
  "manifestVersion": "1.0.0",
  "plugin": {
    "id": "sk.partner-id.portal",
    "partnerId": "partner-id",
    "name": "Partner Portál",
    "version": "2.1.0",
    "changelog": "Pridali sme prehľad transakcií a export do CSV.",
    "requiresReconfiguration": false
  },
  "display": {
    "shortDescription": "Externý portál pre obchodníkov akceptujúcich kartové platby.",
    "categories": ["payments"],
    "tags": ["platby", "portal"],
    "detail": { "description": "## Partner Portál\n\nMarkdown popis, 50 – 20000 znakov." }
  },
  "partner": {
    "name": "Partner s.r.o.",
    "website": "https://partner.example.com",
    "contact": { "emails": ["support@partner.example.com"] },
    "license": { "type": "apache-20" }
  },
  "authentication": {
    "method": "manual",
    "manual": { "redirectUrl": "https://portal.partner.example.com/login?ref=kros" }
  }
}

Všimnite si rozdiely: druhý manifest má changelog vyplnený (je to verzia 2.1.0, teda nie prvá), licenciu apache-20 bez url (nepovinné pri známych licenciách) a objekt tokenBroker vôbec neobsahuje.

Balík .zip

Doplnok sa nahráva ako .zip archív. Samotný manifest.json bez zabalenia do .zip sa nahrať nedá.

Štruktúra archívu

V koreni archívu musí byť manifest.json a presne jedna ikona. Priečinok media/ je nepovinný a musí byť plochý — podpriečinky v ňom nie sú dovolené. Nič iné archív obsahovať nesmie.

doplnok.zip
├── manifest.json        povinné, v koreni
├── icon.png             povinné, presne jedna ikona
└── media/               nepovinné, bez podpriečinkov
    ├── screenshot-1.png
    └── screenshot-2.jpg

Limity archívu

Ikona

Presne jeden súbor icon.<prípona> v koreni archívu. Prípona smie byť png, jpg, jpeg, webp alebo svg.

• Rozmery: obe strany 64 – 1024 px a obrázok musí byť štvorcový. Bannery a iné neštvorcové obrázky sa odmietajú. Pri svg sa rozmery nekontrolujú.
• Obsah musí súhlasiť s príponou: skutočný typ súboru sa zisťuje z jeho hlavičky, nie z názvu. Premenovať .jpg na .png teda nepomôže — balík sa odmietne.

Priečinok media/

Nepovinné náhľadové obrázky doplnku, najviac 10, bez podpriečinkov.

• Prípony: png, jpg, jpeg, webp. svg tu povolené nie je — na rozdiel od ikony.
• Rozmery: najmenej 320 × 180 px, najviac 1920 × 1080 px. Štvorcovosť sa nevyžaduje.
• Obsah musí súhlasiť s príponou, rovnako ako pri ikone.

Prípony a typy obsahu

Kontrola pred nahratím

Validáciu si spustíte sami tým, že balík nahráte, takže chybu vidíte hneď. Toto je zoznam vecí, na ktorých balíky padajú najčastejšie — keď si ho prejdete dopredu, ušetríte si niekoľko kôl.

• plugin.id je celé malými písmenami a jeho stredný segment sa presne zhoduje s plugin.partnerId.
• partner.license.type je zapísaný bez bodky — apache-20, nie apache-2.0. Ak je proprietary alebo other, je vyplnené aj license.url.
• Každá hodnota v display.categories je zo zoznamu povolených kategórií a v poli nie sú duplicity.
• tags neobsahujú medzery ani veľké písmená a každý má aspoň 2 znaky.
• changelog je null pri prvej verzii; pri každej ďalšej má aspoň 20 znakov.
• detail.description má aspoň 50 znakov a shortDescription aspoň 10.
• Je vyplnený aspoň jeden kontaktný kanál — emails, supportUrls alebo partner.website.
• Všetky URL sú https. Jediná výnimka je manual.redirectUrl.
• Vyplnený je len ten objekt, ktorý patrí zvolenému method — druhý chýba alebo je null.
• V tokenBroker.apiKey je placeholder, nie reálny kľúč.
• Ikona je štvorcová, 64 – 1024 px, a v koreni archívu je len jedna.
• V media/ nie je žiadne svg ani podpriečinok.
• Archív má najviac 25 položiek a rozbalený nemá viac ako 15 MB.