Connection scheme
System Module
------------------------------------------------------------------------------
| |
| |
Connection configuration request ----------------------> |
(required rights, connection <---------------------- |
address, etc.) |
| |
| |
Module registration ----------------------> Request to create
request <---------------------- module configuration
| |
| |
User transition ----------------------> |
to the personal account of the module |
------------------------------------------------------------------------------Connection data request
To obtain the data required to connect the module, the system initiates a request {configUrl} to the address specified in the personal account. The data is requested at the moment when the user opens a PopUp with information about the module on the marketplace page in the system.
Module connection request
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.
After that, 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).
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
}Partner account
To enable support for simple connection you have to activate the "Simple connection supported" checkbox in the partner account in the module editing card 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.
To test a simple connection the unpublished module will be displayed in the partner's CRM account associated with the accounting record in the partner's account.