Inicializace

Základní odpověď aplikace do systému Retailys

Odpověď aplikace

Při zavolání rootovské url aplikace je požadována odpověď typu HTTP 200 ve formátu JSON.

Specifikujeme identitu aplikace, uvedeme zde název aplikace, jazyk a její verzi. Také zde můžeme uvést alternativní názvy aplikace v jiných jazycích. Poté zde nastavíme práva pro aplikaci, abychom specifikovali k jakým koncovým bodům na API bude mít jaká práva. Je zde potřeba také nastavit callback pro konfiguraci, jedná se tedy o routu k prvnímu kroku nastavení a to bývá nejčastěji výběr prodejních kanálů případně skladů, jedná li se o aplikaci, která bude primárně pracovat se sklady. A callback-remove pro smazání aplikace, kde se jedná o routu, která se volá v případě, že chceme v naší administraci Retailysu aplikaci odebrat z instance, což by mělo způsobit smazání nastavení aplikace z její databáze, případně smazání kusy kódů přiřazené aplikací přes API k prodejním kanálům, například statický kus javascriptového kódu.

Příklad odpovědi aplikace v požadovaném formátu JSON

{
  "ident": {
    "name": "Zásilkovna",
    "alternative_names": {
      "sk": "Zásielkovňa",
      "hu": "Csomagküldő",
      "pl": "Przesyłkownia",
      "ro": "Coletăria"
    },
    "language": "cs",
    "version": "2.0"
  },
  "rights": [
    {
      "name": "System.Channels",
      "crud": 2
    },
    {
      "name": "System.Orders",
      "crud": 46
    },
    {
      "name": "System.Settings.Companies",
      "crud": 2
    },
    {
      "name": "System.Settings.Stores",
      "crud": 2
    }
  ],
  "callback": "config",
  "callback-remove": "remove"
}

Vysvětlení jednotlivých parametrů

ident : zde je potřeba uvést parametr name obsahující název aplikace, parametr alternative_names nemusíte uvádět, ale je zde možné nastavit různé názvy aplikace vzhledem k jazyku. Dále zde určujeme parametrem language, kde hodnota bude zkratka jazyka. Také je zde možnost uvést parametrem version naší verzi aplikace v případě, že budeme například aplikaci aktualizovat a budeme jí chtít verzovat

rights : tento parametr obsahuje vícerozměrné pole a jednotlivá pole budou tvořena z dvou parametrů tzn name nebo-li název práva a crud, což je hodnota udávající operace, které může aplikace provádět nad jednotlivými endpointy našeho API

Více informací o právech včetně výpočtu hodnoty crud najdete v sekci Uživatelská práva.

callback : např.: "config" je PATH aplikace kam chceme zaslat metodou POST token aplikace pro komunikaci s API Retailys. Výsledná URL, které je tedy voláná je URL aplikace + PATH např.: https://aplikace.cz/config. Tato první callback URL odpovídá JSON formulářem viz. příklad JSON formulář

callback-remove : cesta, kde budeme řešit odstranění nastavení aplikace například https://aplikace.cz/remove a cesta musí vést na adresu aplikace, nemůže vést na jinou doménu.

Nápověda aplikace

Nápověda se zobrazuje jako ikona otazníku vedle konfigurace každé aplikace a pomáhá s integrací a řešením potíží.

Aby bylo možné nápovědu zobrazit, je potřeba aby se nám v aplikaci na adrese /help nebo-li adresa-aplikace/help zobrazovala samotná nápověda například ve formě html kódu. Můžeme například vykreslit šablonu ve funkci nebo souboru, který bude tuto adresu obsluhovat.

Na path /help přichází parametr lang s jazykem přihlášeného uživatele.

HTTP Request - POST parametry

Po zadání adresy aplikace například https://aplikace.cz/help do prohlížeče bychom měli docílit zobrazení textu a například obrázků, které bude obsahovat naše nápověda

Příklad zobrazení nápovědy

Nápověda - zobrazení

Příklad použití renderu šablonovacího systému twig ve frameworku Symfony

    /**
     * @Route("/help", name="help")
     */
    public function help(Request $request): Response
    {
        return $this->render('help/index.html.twig', [
        ]);
    }

Soubor v tomto případě index.html.twig může obsahovat html prvky a také zde můžete používat styly z knihovny Bootstrap 4.

<div class="row">
	<div class="col-12">
		<h1>Hello World!</h1>
	</div>
</div>

Šablonu si můžeme vytvořit dle naší potřeby. Můžeme použít například tabulku a vytvořit si například menu, kde budeme přepínat více záložek. Například Úvod, Instalace nebo-li Implementace a nebo Podpora.

Můžeme dosáhnout například takového výsledku při zobrazení v administraci Retailys

Ukázka nápovědy aplikace v systému Retailys

Ikona aplikace

Požadovaný formát je PNG ve čtvercovém tvaru například o velikosti 64x64 pixelů

Ikona aplikace by se měla nacházet ve veřejném adresáři aplikace a měla by být dostupná na adrese https://aplikace.cz/icon.png , což znamená, že po zadání adresy aplikace a icon.png za lomítkem by se nám měla zobrazit naše ikona aplikace.