Site icon MALL Partner - Marketplace Help

API connection instructions

pavelzunic

The API connection (MPAPI) is used to link your store and the MALL/MIMOVRSTE Partner environment, i.e. to exchange information about products and their variants, transport settings and last but not least to process orders.

The API is based on the so-called REST architecture, which allows accessing and performing operations on data such as data dump, creation, update or deletion of objects (products, transports, etc.).
The API uses a secure HTTPS connection.

For a functional connection it is necessary to obtain a unique key from the MALL Partner - client_id, which is used to authorise the requests sent.

These requests are sent to https://mpapi.mallgroup.com/ in a production environment, regardless of the country in which you offer your goods.
The country is identified by client_id.

All data is sent and returned in JSON format and UTF-8 encoding. The response to the sent request returns always HTTP code, in the corresponding methods also data and possibly paging. 

{
   "result": {
         "code": 200/400/403/404/500,
         "status": OK/ERROR/LIMITED,
         "message": additional message
   },
   "paging": {
         "pages": number of pages,
         "size": number of items on the page,
         "page": current page
   },
   "data": {
          structured data
   }
}

Detailed information on HTTP codes, the use of pagination and especially the prescribed data structure is available in online documentation.

For faster implementation, the following is available MPAPI client (currently only in PHP, version 5.5 and higher is supported). Download information and the latest version can be found at packagist.org/packages/mallgroup/mpapi-client.

Changelog

Online documentation contains up-to-date information. Any changes are recorded in the Changelog section, including the validity date.

API architecture

MP API is based on software architecture REST and secured HTTPS protocol.

API endpoints

1. Transparent proxy

2. Production environment

Authorization

Each request must include authorization key (client id). This key is available to partners in the partner portal.

Data format

All data is in the format JSON and coded as UTF-8. Content type can be set as Content-Type: application/json or Content-Type: application/json; Charset=UTF-8.

Identification of objects

All objects in the interface (e.g. products/variants) must have a unique identifier that is managed by the partner:

  • MALL does not assign any number series to partners,
  • Identifiers can contain combinations of up to 50 characters, the allowed characters are: _ - 0-9 a-z A-Z (underscores, dashes, numbers zero to nine, upper and lower case letters without accents).
  • The identifier must be unique at the partner level

Exceptions are, for example, orders, transport or invoices. In the case of orders, MALL/MIMOVRSTE will generate order_id, which is then available, for example, in list of open orders. This ID is numeric and must be used when processing your order.

Notice:
MALL order_id exceed the maximum allowed integer size for the 32-bit version of PHP. To avoid inconsistent data for orders, please use the 64-bit version.

Retrieved from

The output is in the following structure:

{
    "result": {
        "code": 200/400/403/404/500,
        "status": OK/ERROR/LIMITED,
        "message": additional error information
    },
    "paging": {
        "pages": number of pages,
        "size": number of objects on a page,
        "page": number of current page
    },
    "data": {
        data structure
    }
}

DELETE requests do not return any content (code 204).

Result

The result returns HTTP code, status and any error message.

Pagination

Object paging is used when the output is divided into multiple pages.
Pagination can be set by calling the URL with parameters page and page_size. The default page size (and also the recommended maximum value) is 100.

Example:
https://mpapi.mallgroup.com/v1/products?client_id={clientId}&page={page}&page_size={pageSize}

Data

The data structure varies depending on the endpoint and is described for each endpoint separately in online documentation.

HTTP status codes

API functions

Functions API are called by appropriate methods HTTP:

Data validation

API requests are verified. If there are any errors that need to be fixed, a list of errors is returned in the body of the response.

Optional parameters

If a property is optional and you don't want to use it, don't put it in the API request. If you set it with an empty value, an error message will be returned Key {key} does not exist or is empty.

Product images

To update the product/variant image, the URL of the image must be changed.
For example, by adding a parameter in the form TIMESTAMP or Product ID/variants to the URL of the image.
The maximum resolution of the images is 2000 px x 2000 px, the minimum image size is 100 KB and the maximum size is 2 MB. The maximum number of images per product is 20. Image URL must not contain spaces and diacritics.

Energy labels

Guidelines for new energy labels

Protection against unintended changes in product price

There are certain risks when a partner updates products on different e-shops with different currencies.
It may happen that the partner sends the price of the product in the wrong currency. In order to partially eliminate this risk, a threshold is set to protect the price of the product.
The allowed price difference between the old and new price of the product/variant is 30 %.

If the price change of the product/variant is higher than the limit, it is returned in the response force_token and the product/variant are not updated.

A product with a significant price difference can therefore only be upgraded using force_token from a failed product update. In the next request, you must send the retrieved force_token as a URL parameter.

Example:
https://mpapi.mallgroup.com/v1/products/{productId}?client_id={clientId}&force_token={forceToken}

By updating the product price with the help of force_token, the partner confirms that the new price is correct and that he accepts full responsibility for the new price.
In these cases, caution is in order locally and therefore it is not advisable to use force_token automatically. All changes and token usage are recorded by MALL.
In countries outside the CZ, use as an amount separator period ".".

Example:

{
  "errorCodes": [
    {
      "message": "Difference between current price ({value of current price}) and new price ({value of new price}) for product "{product id}" is greater than 30% ({real percentage difference}). To confirm this change, use attached force token.",
      "errorCode": "INCORRECT_PRODUCT_PRICE_DIFFERENCE",
      "errorAttributes": {
        "current": "currentPrice",
        "new": "newPrice",
        "id": "productId"
      }
    }
  ],
  "result": {
    "code": 400,
    "status": "ERROR",
    "message": "Difference between current price ({value of current price}) and new price ({value of new price}) for product "{product id}" is greater than 30% ({real percentage difference}). To confirm this change, use attached force token."
  },
  "data": {
    "key": "product.variants",
    "data": {
      "forceToken": "b3f7d1feca4c649e3493b466cbe0e6795bc6f679",
      "variantIndex": 0
    }
  }
}

API endpoints

How useful was this post?

Click on the star to rate the post!

Average rating: 3 / 5. Number of votes: 4

No one has voted yet. Be the first to rate this post.

Exit mobile version