Developers /

Placement of the module in the Marketplace

(redirected from Developers.Marketplace)

Introductory provisions

You can develop your own module for retailCRM and place it in the Marketplace. The module can either be free of charge or paid. Before placing the module, you need to register as a retailCRM partner and sign the agreement. To do this, contact us via the form on the website.

Module development

Your module can perform all the functions that are available in API. A complete list of API methods is available in the methods reference book. To work with API, you need to create an API key. You must understand which API methods are required for the module to work. In the future, in the module instructions, you will need to specify which API methods the user should allow for the API key that is provided to your module. When activating the module using the GET /api/credentials method, you can check if all the required methods are allowed by the user.

It is important to familiarise yourself with the system’s API rules. This will help you to understand API limitations and diagnose API-related errors.

Main module requirements

  1. The module should extend retailCRM’s user-defined functions and bring clear value to the product. Solutions duplicating retailCRM’s standard functions will not be published. The publication of a module may also be refused if a similar function is currently under development by retailCRM.
  2. Integration implies a physical automatic data exchange between retailCRM and an external system. Opening an external service interface from retailCRM is not enough to publish the module.
  3. When receiving data from retailCRM via a module, if it is possible to implement both using API and a trigger, the priority should be given to API in order to minimise the customer's work when connecting and configuring the module.
  4. The module should increase the ease of data exchange between retailCRM and external solutions to prevent the customer from having to switch between windows and admin panels of various services.
  5. The description of the module must correspond directly to its functionality. The name of the module should be descriptive and should not contain elements of retailCRM’s corporate identity.
  6. Any restrictions in the operation of the module, or its inability to process data caused by the limitation of the final system with which the integration is carried out via the module, should be described in the documentation.
  7. The description of the module should clearly list which API methods are required to correctly install and operate the module. If a common personal account with the option to manage several modules is implemented in your system (for authorisation to which you need an API key), this should be specified in the documentation.
  8. For delivery modules in retailCRM, there are an extensive number of functions available, in particular, the uploading of parcels to the delivery service and the ability to edit, change or delete them. If the module cannot maintain these functions properly, you must specify this in the module’s instructions.
  9. The module should not ask for a user login and password for authorisation in retailCRM. To obtain the necessary data from the customer's account, you must use the API key.
  10. The module should provide information about API related errors. Error messages arising due to incorrect data formatting, incorrect data processing by customer managers and/or a failure directly in the final system (with which the module is integrated) should be clearly displayed, be understandable and sufficiently informative. The module cannot output standard errors such as Server error or stack trace.
  11. There should be no errors in the operation of the module, therefore you also need to make sure that all links and mechanisms for connecting and configuring the module are fully operational. If it is difficult to connect and configure a module, this will lead to a negative outcome when it comes to moderation, even if the module is installed on the partner's test system and it is possible to check performance.
  12. When setting up mapping between fields in two systems, it is necessary that the data from both systems are always up-to-date on the settings page. Developers should not create any kind of fields/lists of data which cannot be received from the external system. Otherwise the data exchange, and therefore the module, will not work.All data must be generated in advance and updated as necessary.
  13. The module and its description should not contain offensive, obscene information, incitement to violence, pornography, racism, and other materials prohibited by the legislation of the Russian Federation.
  14. We recommend that you log API requests and responses and that this data is stored for between 1 and 4 weeks/1 month, to be used when solving integration issues.
  15. The module may not be permitted for publication in the retailCRM marketplace without explaining the reasons by the decision of the moderator.
  16. When re-sending a module for moderation, a comment must be added describing what changes were made and the specific remarks/issues that have been corrected.
  17. The number of times a module can be sent for moderation is currently not limited, however, in cases of frequent negative decisions (if # the number of attempts is more than 5), the module may be lowered in priority during verification.

Module activation and interaction with retailCRM

The general path of module activation is as follows: 

Module             RetailCRM               User 
           ------------------------------------------------------------------
                      |                    |                     |
1.                    |            Creation of API Key  -------->|
                      |                    |                     |
                      |                    |                     |
                      |                    |                     |
2.                    |          Presses the “Connect” button    | 
                      |            in the module card ---------->|
                      |            in the Marketplace            |
                      |                    |                     |
                      |                    |                     |
                      |                    |                     |
                      |                    |                     |
3.                    |                    |            Redirecting the User 
                      |<-------------------|<--------to the form for configuring  
                      |                    |          and enabling the module
4.                    |<------------Fills in the form            |
                      |                    |                     |
5.          Checking the API key,--------->|-------------------->|
            rights for the API key         |                     |
              and API versions             |                     |
                      |                    |                     |
6.           Registering the module        |                     |
               in the retailCRM            |                     |
                    account------------------------------------> |
                      |                    |                     |
7.           Redirecting the user--------->|-------------------->| 
            to the retailCRM account       |                     |
        -------------------------------------------------------------------

Let's take a look at the steps in this process:

Step 1

The user enters the Marketplace and sees your module, for example:

By clicking on the module, a description of the module's functions and connection instructions opens:

The information displayed in the module card is entered via the partner account. This is discussed in more detail in the Publishing a module section.

The user follows the instructions through to the API keys management section and creates a key for your module.

Step 2

The user in the module card clicks the Connect button.

Step 3

The system redirects the user to the module settings form. The address of this page is set when the module is published. When redirecting, the GET parameter account is passed, which contains the address of the retailCRM account where the module is activated, for example, http://some-service.pro/cabinet?account=https://some.retailcrm.pro.

Step 4

On the module settings page, the user, as a rule, needs to enter their account address (where the account value from the GET parameter, if passed, should be substituted) and the API key, as well as specifying additional module settings.

Step 5

User sends a form with configured settings. At this moment, the module should check:

  1. Whether API can be accessed using the specified API key. To do this, you can make the GET /api/api-versions request, at the same time checking if the API version used for the module is available.
  2. Check the rights granted to the API key using the GET /api/credentials method. If rights have not been granted, the user should be informed.
  3. Check other module settings.

Step 6

The module then registers itself in the specified retailCRM account. Registration is completed using the POST /api/v5/integration-modules/{code}/edit method. When registering, the following data is specified:

Symbolic code of the module integrationModule[integrationCode]

This code must match the module code that was specified when the module was published. Based on this, the system will recognise that this is your module. This is important, for example, in the case of a paid module, for which money is debited from the user and is transferred to you as a partner.

Symbolic code of module copies integrationModule[code]

If your module allows you to register several copies within one user account, the code must be unique. This is useful, for example, in the case of delivery service integration modules, since users often have several accounts in the delivery service for different legal entities.

If support for several copies within a single account is not expected, then this parameter can be the same as integrationModule[integrationCode].

Module activity integrationModule[active]

For the module to be activated in the account, it is required that you specify true in this parameter. If the module is paid, this is the basis for debiting the amount from the user for the next month of use, providing that a trial period is not configured for the module.

Unique customer hash key integrationModule[clientId]

In this parameter, you need to pass the generated hash key, which will only be known to you and this retailCRM account. This parameter will be passed in all requests from retailCRM and allows the module to determine that these requests came from this particular account, and not by a third party.

Base URL integrationModule[baseUrl]

Base URL, relative to which the addresses will be built, where the retailCRM account makes requests. For example https://some-service.pro/retailcrm/api.

The relative paths of concrete methods integrationModule[actions][]

You need to set the relative path of the integrationModule[actions][activity] method, to which the retailCRM account will execute the request when:

The format of this callback is described here POST {integrationModule["baseUrl"]}/{integrationModule["actions"]["activity"]}.

After receiving a request to deactivate or freeze a module, the module must accordingly terminate or suspend its operations on this account. After receiving a request to activate or unfreeze a module, the module must accordingly perform the opposite. When renaming the system, you need to save the new system URL that was sent in the request, and send all subsequent requests to the system to this URL.

Personal account address integrationModule[accountUrl]

In this parameter you must enter the full address of the personal account on the module side. When this parameter is passed after activation in the module card in retailCRM, the user can access the button to go to the account, where they can subsequently change the module settings. When the button is clicked, the user is redirected to the specified address using the POST method with the passed parameter clientId. If there is authorisation on the module side, you need to transparently authorise the user based on the clientId and redirect them to the module settings editing section.

Parameters for displaying the module before publication in the Marketplace

The name of the module, the logo of the module and the country in which the module works are specified when publishing the module, but to check their correct application at the stage of module development, you can transfer them when activating the module in the integrationModule[name], integrationModule[logo] and integrationModule[availableCountries] parameters. After the module is published in the Marketplace, these parameters are ignored.

Parameters for specific module types

For Delivery, Telephony and Warehouse related modules, additional settings must be transferred which are necessary for the full operation of these types of modules. More information about the development procedure for these types of modules is written in the documentation for each of the module types:

Paid modules: points to note

If your module is paid and does not have a trial period, at the moment of the module’s activation retailCRM will try to debit the payment for the next month of use from the user's balance. If the payment failed to be debited, the POST /api/v5/integration-modules/{code}/edit method will present an error with the HTTP 402 status. In this case, you need to inform the user that there are not enough funds on their account to activate the module and offer to redirect them to their account to top up the balance.

Step 7

If the module was activated successfully, then you need to redirect the user back to their retailCRM account on the Marketplace page.

RetailCRM
Print ∙ Edit ∙ History
Page last modified on April 05, 2021, at 11:52 AM