If you do not plan to publish a module in the Marketplace use the connection method described in a separate article. In other cases use the method described below.
Enabling support for simple module connection
To enable support for simple connection you should activate the " Simple connection supported" checkbox in the module editing card in the partner account and specify the address to receive the configuration in the "URL for simple connection configuration request" field. After saving the module card, a secret string will be generated in the "Secret" field to verify the connection request from the system.
Take into consideration the Update permissions method for the API key which is needed to update the API key permissions. In this case the available rights will depend on those specified in the partner account.
To test a simple connection the unpublished module will be displayed in the partner CRM account associated with the accounting record in the partner account.
Module connection and activation
The general scheme of module activation is as follows:
Module User System
------------------------------------------------------------------
1. | Goes to the marketplace |
| and opens your module -----> Receives data for
| | connecting the module
| <-------------------------------------------- by initiating a request
| | {configUrl}
| | |
2. | Clicks |
| the "Connect" button |
| in the Module card -----> To connect the module
| in the Marketplace the system initiates a request
| <--------------------------------------------- {registerUrl}
| | |
3. Module registration | |
in the systemе ------------------------------------------> |
account | |
| | |
| | Redirecting
4. | <------------------------------------------- the user
| | to the settings form
| | |
5. Redirecting | |
the user ---------------> | -----------------------> |
to the system | |
account | |
| | |
| The user can go |
| to the personal account of the module |
| for its further configuration |
------------------------------------------------------------------Let's review the main steps of this process.
Step 1. Information in the module
The user enters the Marketplace and sees your module. Clicking on the module opens a description of the module features and instructions for connecting.
The information displayed in the module card is entered via the partner account. This is described in more detail in the Publishing a module section.
When PopUp is opened, the data required to connect the module is also received. To do this the system initiates a request to the address specified in the partner account.
Step 2. Module connection
The user clicks the Connect button in the module card.
To connect the integration module the system initiates a request {registerUrl} to the address specified in the response to the request {configUrl}..
The module is connected at the moment when the user clicks on the "Connect" button in PopUp. Upon the system request the module must verify the request using the register[token] parameter. This token is a hash code generated on the basis of the transferred API key by the hmac method using the sha256 algorithm, where a secret string from the personal account in the partner account is used as a secret.
For example, in php the token can be calculated as follows: hash_hmac('sha256', '<api-key>', '<secret>'), where <api-key> is the transferred key, <secret> is the secret string from the partner account. If the result of the function execution is not equal to the transferred token, then the request is invalid and most likely it did not come from the system.
Error processing
If an error occurs you have to return the response (HTTP status 200) in the following format:
{
"success": false,
"errorMsg": "Error text" // Error message. Will be displayed to the user in the module card
}Step 3. Module registration
Using the POST /api/v5/integration-modules/{code}/edit method, make a request to the system with the received data for module registration and, if successful, return the link to the created user account in the accountUrl field in the response. After that, the user will be redirected to his personal account via the specified link as if he went to his personal account via the link on the module editing page in the system (POST request will be made with the clientId parameter). When registering, the following data is specified:
Symbol code of the module integrationModule[integrationCode]
This code must match the module code specified when publishing the module. Based on this, the system will understand 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 which is then transferred to you as a partner.
Symbol code of the module instance integrationModule[code]
If your module allows you to register multiple instances of the module within one account, this code must be unique. This is helpful, for example, in the case of integration modules with delivery services, since it is not uncommon for a user to have several delivery service accounts for different legal entities.
If multiple instances are not intended to be supported within a single account, this parameter may match the integrationModule[integrationCode].
Module activity integrationModule[active]
It is required to specify true in this parameter in order for the module to be activated in the account. If the module is paid, this is the reason for charging the user for the next month of using the module, but provided that a trial period is not set up for the module.
Customer's unique hash key integrationModule[clientId]
In this parameter you need to transfer the generated hash key which will be known only to you and this account of the system. This parameter will be transferred in all requests from the system and allows the module, firstly, to determine that these requests came from this particular account, and secondly, that they were sent by this particular account and not by a third party.
Basic URL integrationModule[baseUrl]
The basic URL, relative to which the addresses will be built, where the system account executes requests. For example https://some-service.ru/simla/api.
Relative paths of specific methods integrationModule[actions][]
It is necessary to set the relative path of the method integrationModule[actions][activity] to which the system account will execute a request when:
- the user activates/deactivates the module
- the module is frozen/unfrozen by the system at the moments when it fails to debit payments for the next month of module use
- renaming the system.
The format of this callback is described here POST {integrationModule["baseUrl"]}/{integrationModule["actions"]["activity"]}.
In case of receiving a request to deactivate or freeze the module, the module must stop or suspend its work on this account accordingly. In case of receiving a request to activate or unfreeze the module, the module must perform the reverse actions accordingly. When renaming the system, you need to save the new system URL sent in the request, and send all subsequent requests to the system to this URL.
Personal account address integrationModule[accountUrl]
In this parameter the full address of the personal account on the module side is transferred. When transferring this parameter after activation in the module card in the system the user has access to the button for going to the account where he 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 transferred clientId parameter. If authorization is present on the module side, it is necessary to authorize the user on the basis of the clientId transparently and redirect to the module settings editing section.
Module display parameters before publishing in the Marketplace
The module name, the module logo and the countries in which the module works are set when publishing the module, but to verify their correct application during the module development phase you can transfer them when activating the module in the parameters integrationModule[name], integrationModule[logo] and integrationModule[availableCountries]. After the module is published in the Marketplace these parameters are ignored.
Parameters for special module types
For modules of the Delivery, Telephony and Warehouse types it is required to transfer additional settings that are necessary for the full operation of these types of modules. More details about the order of development of these module types are described in the documentation for each module type:
- Telephony
- Delivery service
- Payment system
- Warehouse system and fulfillment
- Recommendations
- Bots
- Messengers
Features of paid modules
If your module is paid and it does not have a trial period, at the time of the module activation the system tries to charge the user's balance for the next month of using the module. If the payment fails to be deducted, POST method /api/v5/integration-modules/{code}/edit will generate an error with HTTP status 402. In this case you need to inform the user that there are not enough funds on his account to activate the module and return an explanatory message to the errorMsg field.
Step 4. Redirection to the module settings
If the module is activated successfully the system will automatically redirect the user to the module settings page.
Step 5. Personal account of the module
After connecting the module the transition to the personal account of the module is performed by a POST request with the transfer in the clientId parameter of the customer's unique cache key specified when publishing the module (clientId).