Initialization

Basic application response to the Retailys system

Application response

An HTTP 200 response in JSON format is required when calling the root application url.

We specify the identity of the application, the name of the application, the language and its version. We can also list alternative application names in other languages ​​here. Then we set the rights for the application here to specify which endpoints on the API it will have what rights. It is also necessary to set up a callback for configuration, so this is the route to the first step of setup, and this is most often the selection of sales channels or warehouses, if it is an application that will primarily work with warehouses. A callback-remove to delete an application, which is a route that is called in case we want to remove the application from the instance in our Retailys administration, which should cause deleting the application settings from its database, or deleting pieces of code assigned to the application via API to sales channels, such as a static piece of javascript code.

Example of an application response in the required JSON format

{
  "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"
}

Explanation of individual parameters

ident : you need to specify the name parameter containing the application name, you do not need to specify the alternative_names parameter, but it is possible to set different application names with respect to the language. Here we specify the language parameter, where the value will be the shortcut of the language. There is also the option to specify the version parameter of our application version in case, for example, we update the application and we want to version it

rights : this parameter contains a multidimensional field and the individual fields will consist of two parameters, ie name and crud, which is a value indicating the operations that the application can perform on individual endpoints of our API

For more information on rights, including the calculation of the crud value, see the section User's rights.

callback : for example, https://application.com/config and the path must lead to the application address, it cannot lead to another domain on which we will solve the first step of setup, ie the selection of sales channels, we will also receive a token for communication with the API

callback-remove : the path where we will solve the deletion of the application settings, for example https://application.com/remove and the path must lead to the application address, it cannot lead to another domain.

Application help

Help appears as a question mark icon next to each application's configuration and helps with integration and troubleshooting.

In order to be able to display help, it is necessary for the help itself to be displayed in the application at / help or application-address / help, for example in the form of html code. For example, we can draw a template in a function or file that will handle this address.

The lang parameter with the language of the logged in user comes to path / help.

After entering the address of the application, for example https://application.com/help in the browser, we should achieve the display of text and, for example, images that will contain our help.

Example of help display

Example of using a twig template system render in the Symfony framework

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

In this case, the file index.html.twig can contain html elements and you can also use styles from the Bootstrap 4 library here.

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

We can create a template according to our needs. For example, we can use a table and create a menu where we will switch multiple tabs. For example, Introduction, Installation or Support.

For example, we can achieve such a result when displayed in the Retailys administration

Application icon

The required format is a square PNG, for example, 64x64 pixels in size.

The application icon should be located in the public application directory and should be available at https://application.com/icon.png, which means that after entering the application address and icon.png after the slash, our icon should be displayed.

PreviousApplication developmentNextConfiguration

Last updated