This is a beta release of documentation for Magento 2.4, published for previewing soon-to-be-released functionality. Content in this version is subject to change. Links to the v2.4 code base may not properly resolve until the code is officially released.

Create an integration

Edit on GitHub
Log an Issue

An integration enables third-party services to call the Magento web APIs. The Magento APIs currently supports Accounting, Enterprise Resource Planning (ERP), Customer Relationship Management (CRM), Product Information Management (PIM), and marketing automation systems out of the box.

Implementing a simple integration requires little knowledge of PHP or Magento internal processes. However, you will need a working knowledge of

Before you begin creating a module, make sure that you have a working installation of Magento 2.0, and the Magento System Requirements.

To create an integration, follow these general steps:

  1. Create a module with the minimal structure and configuration.
  2. Add files specific to the integration.
  3. Install the module.
  4. Check the integration.
  5. Integrate with your application.

Create a skeletal module

To develop a module, you must:

  1. Create the module file structure. The module for an integration can be placed anywhere under the Magento root directory, but the recommended location is <magento_base_dir>/vendor/<vendor_name>/module-<module_name>.

    Also create etc, etc/integration, and Setup subdirectories under module-<module_name>, as shown in the following example:

    1

    cd <magento_base_dir>

    1

    mkdir -p vendor/<vendor_name>/module-<module_name>/etc/integration

    1

    mkdir -p vendor/<vendor_name>/module-<module_name>/Setup

    For more detailed information, see Create your component file structure.

  2. Define your module configuration file. The etc/module.xml file provides basic information about the module. Change directories to the etc directory and create the module.xml file. You must specify values for the following attributes:

    AttributeDescription
    name A string that uniquely identifies the [module](https://glossary.magento.com/module).
    setup_version The version of Magento the component uses

    The following example shows an example etc/module.xml file.

    1
2
3
4
5
6
7
8
9
10
11
12
13
14

    <?xml version="1.0"?>
<!--
   /**
   * Copyright © Magento, Inc. All rights reserved.
   * See COPYING.txt for license details.
   */
   -->
   <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
       <module name="Vendor1_Module1" setup_version="2.0.0">
            <sequence>
                <module name="Magento_Integration"/>
            </sequence>
       </module>
     </config>

    Module Magento_Integration is added to “sequence” to be loaded first. It helps to avoid the issue, when a module with integration config loaded, that leads to a malfunction.

  3. Add your module’s composer.json file. Composer is a dependency manager for PHP. You must create a composer.json file for your module so that Composer can install and update the libraries your module relies on. Place the composer.json file in the module-<module_name> directory.

    The following example demonstrates a minimal composer.json file.

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

      {
     "name": "Vendor1_Module1",
     "description": "create integration from config",
     "require": {
        "php": "~7.1.3|~7.2.0|~7.3.0",
        "magento/framework": "2.0.0",
        "magento/module-integration": "2.0.0"
     },
     "type": "magento2-module",
     "version": "1.0",
     "autoload": {
        "files": [ "registration.php" ],
        "psr-4": {
           "Vendor1\\Module1\\": ""
        }
     }
  }

    For more information, see Create a component.

  4. Create a registration.php file The registration.php registers the module with the Magento system. It must be placed in the module’s root directory.

    1
2
3
4
5
6
7
8
9
10
11

    <?php
/**
* Copyright © Magento, Inc. All rights reserved.
* See COPYING.txt for license details.
*/

\Magento\Framework\Component\ComponentRegistrar::register(
\Magento\Framework\Component\ComponentRegistrar::MODULE,
'Vendor1_Module1',
__DIR__
);

  5. Create an install class. Change directories to your Setup directory. Create a InstallData.php file that installs the integration configuration data into the Magento integration table.

    The following sample is boilerplate and requires minor changes to make your integration work.

    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

    <?php
namespace Vendor1\Module1\Setup;

use Magento\Framework\Setup\ModuleContextInterface;
use Magento\Framework\Setup\ModuleDataSetupInterface;
use Magento\Integration\Model\ConfigBasedIntegrationManager;
use Magento\Framework\Setup\InstallDataInterface;

class InstallData implements InstallDataInterface
{
    /**
     * @var ConfigBasedIntegrationManager
     */

    private $integrationManager;

    /**
     * @param ConfigBasedIntegrationManager $integrationManager
     */

    public function __construct(ConfigBasedIntegrationManager $integrationManager)
    {
        $this->integrationManager = $integrationManager;
    }

    /**
     * {@inheritdoc}
     */

    public function install(ModuleDataSetupInterface $setup, ModuleContextInterface $context)
    {
        $this->integrationManager->processIntegrationConfig(['testIntegration']);
    }
}

    In the following line

    $this->integrationManager->processIntegrationConfig(['testIntegration']);

    testIntegration must refer to your etc/integration/config.xml file, and the integration name value must be the same.

    The following example demonstrates a minimal config.xml file.

    1
2
3
4
5
6
7

     <integrations>
    <integration name="TestIntegration">
       <email>someone@example.com</email>
       <endpoint_url>https://example.com</endpoint_url>
       <identity_link_url>https://example.com/identity_link_url</identity_link_url>
    </integration>
 </integrations>

    Also, be sure to change the path after namespace for your vendor and module names.

Create integration files

Magento provides the Integration module, which simplifies the process of defining your integration. This module automatically performs functions such as:

  • Managing the third-party account that connects to Magento.
  • Maintaining OAuth authorizations and user data.
  • Managing security tokens and requests.

To customize your module, you must create multiple XML files and read through others files to determine what resources existing Magento modules have access to.

The process for customizing your module includes

Define the required resources

The etc/integration/api.xml file defines which API resources the integration has access to.

To determine which resources an integration needs access to, review the permissions defined in each module’s etc/acl.xml file.

In the following example, the test integration requires access to the following resources in the Sales module:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<integrations>
    <integration name="testIntegration">
        <resources>
            <!-- To grant permission to Magento_Log::online, its parent Magento_Customer::customer needs to be declared as well-->
            <resource name="Magento_Customer::customer" />
            <resource name="Magento_Log::online" />
            <!-- To grant permission to Magento_Sales::reorder, all its parent resources need to be declared-->
            <resource name="Magento_Sales::sales" />
            <resource name="Magento_Sales::sales_operation" />
            <resource name="Magento_Sales::sales_order" />
            <resource name="Magento_Sales::actions" />
            <resource name="Magento_Sales::reorder" />
        </resources>
    </integration>
</integrations>

Pre-configure the integration

Your module can optionally provide values in configuration file config.xml, so that the integration can be automatically pre-configured with default values. To enable this feature, update the config.xml file in the etc/integration directory.

If you pre-configure the integration, the values cannot be edited from the admin panel.

The file defines which API resources the integration has access to.

1
2
3
4
5
6
7

<integrations>
   <integration name="TestIntegration">
       <email></email>
       <endpoint_url></endpoint_url>
       <identity_link_url></identity_link_url>
   </integration>
</integrations>
Element Description
integrations Contains one or more integration definitions.
integration name="" Defines an integration. The name must be specified.
email An email to associate with this integration.
endpoint_url

Optional. The [URL](https://glossary.magento.com/url) where OAuth credentials can be sent when using OAuth for token exchange. We strongly recommend using https://.

See OAuth-based authentication for details.
identity_link_url Optional. The URL that redirects the user to link their 3rd party account with the Magento integration.

Install your module

Use the following steps to install your module:

  1. Run the following command to update the Magento database schema and data.

    1

    bin/magento setup:upgrade</code>

  2. Run the following command to generate the new code.

    In Production mode, you may receive a message to ‘Please rerun Magento compile command’. Enter the command below. Magento does not prompt you to run the compile command in Developer mode.

    1

    bin/magento setup:di:compile

  3. Run the following command to clean the cache.

    1

    bin/magento cache:clean

Check your integration

Log in to Magento and navigate to System > Extensions > Integrations. The integration should be displayed in the grid.

Integrate with your application

Before you can activate your integration in Magento, you must create two pages on your application to handle OAuth communications.

  • The location specified in the identity_link_url parameter must point to a page that can handle login requests.

  • The location specified in the endpoint_url parameter (Callback URL in Admin) must be able to process OAuth token exchanges.

Login page

When a merchant clicks the Activate button in Admin, a pop-up login page for the third-party application displays. Magento sends values for oauth_consumer_key and success_call_back parameters. The application must store the value for oauth_consumer_key to tie it to the login ID. Use the success_call_back parameter to return control back to Magento.

Callback page

The callback page must be able to perform the following tasks:

  • Receive an initial HTTPS POST that Magento sends when the merchant activates integration. This post contains the Magento store URL, an oauth_verifier, the OAuth consumer key, and the OAuth consumer secret. The consumer key and secret are generated when the integration is created.

  • Ask for a request token. A request token is a temporary token that the user exchanges for an access token. Use the following API to get a request token from Magento:

    POST /oauth/token/request

    See Get a request token for more details about this call.

  • Parse the request token response. The response contains an oauth_token and oauth_token_secret.

  • Ask for an access token. The request token must be exchanged for an access token. Use the following API to get a request token from Magento:

    POST /oauth/token/access

    See Get an access token for more details about this call.

  • Parse the access token response. The response contains an oauth_token and oauth_token_secret. These values will be different than those provided in the request token response.

  • Save the access token and other OAuth parameters. The access token and OAuth parameters must be specified in the Authorization header in each call to Magento.

© 2020 Magento. All rights reserved.