meestexpress-api-magento2-module-logo

MeestExpress API Magento2 module

Structure:
1. Functionality
2. Compatibility
3. How to install MeestExpress API
  3.1. Install MeestExpress API via composer
  3.2. Install ready-to-paste package
4. How to uninstall MeestExpress API
  4.1. Installed MeestExpress API via composer
  4.2. Installed ready-to-paste package approach
5. User guide
6. Developer guide
  6.1. Sample module how to use this MeestExpress API module
7. Contribution


MeestExpress is one of the biggest postal and courier companies in Ukraine that organize delivery of parcels, money, letters for businesses and individuals. More information you can find here https://www.meest-express.com.ua
This module helps to communicate with MeestExpress API v3.0


1. Functionality

  • Authenticate in MeestExpress system
  • Save token for future request
  • Use all endpoints of MeestExpress API

2. Compatibility

  • Magento 2.1, 2.2, 2.3

3. How to install MeestExpress API

We are going to install MeestExpress API module. There are 2 options:

  • via composer
  • via copy paste approach

3.1. Install MeestExpress API via composer (recommended)

Run the following commands in Magento 2 root folder:

composer require bdn/magento-2-meestexpress-api
php bin/magento setup:upgrade
php bin/magento php bin/magento setup:di:compile

3.2. Install ready-to-paste package

  • Download the latest version from Github
  • Unzip it to your project. Folder: app/code/Bdn/MeestExpress
  • Run the following commands in Magento 2 root folder:
php bin/magento setup:upgrade
php bin/magento php bin/magento setup:di:compile

4. How to uninstall MeestExpress API

We will uninstall MeestExpress API module. Choose the way how you installed the module previously.

4.1. Installed MeestExpress API via composer

Run the following commands in Magento 2 root folder:

php bin/magento module:disable Bdn_MeestExpress
php bin/magento setup:di:compile
composer remove bdn/magento-2-meestexpress-api

4.2. Installed ready-to-paste package approach

  • Delete the folder: app/code/Bdn/MeestExpress
  • Run the following commands in Magento 2 root folder:
php bin/magento module:disable Bdn_MeestExpress
php bin/magento setup:di:compile

5. User guide

  • Login into Magento Admin Panel
  • Go to the Admin Panel > Stores > Configuration > Services > MeestExpress and insert your MeestExpress credentials
    meestexpress-api-magento2-module-save-credential-gif
  • Go to the terminal and run command for the authentication and saving the token for future requests to the MeestExpress system.
php bin/magento bdn:meestexpress:auth

If thecredentials are correct, you will see this:
meestexpress-api-magento2-module-success-auth-gif


If the credentials are not correct, you will see this:
meestexpress-api-magento2-module-failed-auth-gif

6. Developer’s guide

Developer can use this module like a service via contsuctor Dependency Injection

  • Add service to your constructor
/**
 * @var \Bdn\MeestExpress\Model\Service\Api
 */
private $meestExpressApi;

/**
 * Your constructor.
 *
 * @param \Bdn\MeestExpress\Model\Service\Api $meestExpressApi
 */
public function __construct(
    \Bdn\MeestExpress\Model\Service\Api $meestExpressApi
) {
    $this->meestExpressApi = $meestExpressApi;
}

  • Use public function in any place where you need it.
$this->meestExpressApi->countrySearch('Ukra');
$this->meestExpressApi->zipCodeSearch('79038');
$this->meestExpressApi->tracking('TAC-2550636');

6.1 Sample module how to use this MeestExpress API module

Here you can find a sample module, which shows how a developer can use MeestExpress API module.
IMPORTANT: MeestExpress API module SHOULD BE installed before!

Steps:

  • Download and unpack sample module from here
  • Move it to the folder: app/code
  • Run the following commands
php bin/magento module:enable Bdn_MeestExpressUsage
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

{ 
   "status":"OK",
   "info":{ 
      "fieldName":"",
      "message":"",
      "messageDetails":""
   },
   "result":[ 
      { 
         "countryID":"c35b6195-4ea3-11de-8591-001d600938f8",
         "countryDescr":{ 
            "descrUA":"\u0423\u041a\u0420\u0410\u0407\u041d\u0410",
            "descrRU":"\u0423\u041a\u0420\u0410\u0418\u041d\u0410",
            "descrEN":"UKRAINE "
         }
      }
   ]
}

  • Test other available methods in the file: app/code/Bdn/MeestExpressUsage/Controller/Index/Index.php

RECOMMENDATION: Create a cron job for getting new access token from the MeestExpress service

  • Create a class which calls auth method and save a return api token
    app/code/Bdn/MeestExpressUsage/Cron/Auth.php
<?php
declare(strict_types=1);

namespace Bdn\MeestExpressUsage\Cron;

use Bdn\MeestExpress\Api\ApiInterface;
use Bdn\MeestExpress\Model\Config\MeestExpressConfig;

class Auth
{

    /**
     * ApiAuth constructor.
     *
     * @param ApiInterface       $apiService
     * @param MeestExpressConfig $meestExpressConfig
     */
    public function __construct(
        ApiInterface $apiService,
        MeestExpressConfig $meestExpressConfig
    ) {
        $this->apiService         = $apiService;
        $this->meestExpressConfig = $meestExpressConfig;
    }

    public function execute()
    {
        $response = $this->apiService->auth();
        $this->meestExpressConfig->saveApiToken($response['result']['token']);
    }
}
  • Create a crontab
    app/code/Bdn/MeestExpressUsage/etc/crontab.xml
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Cron:etc/crontab.xsd">
    <group id="meestexpress_auth">
        <job name="auth" instance="Bdn\MeestExpressUsage\Cron\Auth" method="execute">
            <schedule>* */6 * * *</schedule>
        </job>
    </group>
</config>

7. Contribution

This MeestExpressAPI magento2 module has been covered for 40% of all native MeestExpress API functionality. The main part is ready to use. I want to hear a feedback from developers and users, for the future support of this module.
If you are developer, you can easily find some issues(functions) that need to be covered.
Everything is described in Github Issue Page.


Conclusion

We have installed MeestExpress API module for Magento2 via one of the best ways that you can follow: a composer or a copy paste approach. Saved credentials for accessing to API. Understood how the developers can easily use this module for their purpose.
I will appreciate some feedback from you. Leave a comment below or find any convenient way in the contact page, I’ll answer as soon as possible, Thank You.

Sincerely yours,
Bohdan.

Leave a Comment