API connection instructions

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

• For independent API testing, you can use a transparent proxy (you can call modes from the online documentation Mock Server or Debugging Proxy),
• click on the Inspector link in the top menu to monitor your proxy banner requests,
• if you don't use a transparent proxy, you can send requests directly to URI endpoints on the production environment.

2. Production environment

• The URL of the production API can be found at https://mpapi.mallgroup.com/v1/, the URL is valid for each language, but different ones apply for each country client_id.

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.

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

• 200 OK - everything is fine, the data is returned correctly,
• 201 Created - the submitted data has been received and the entity has been created,
• 204 No content - the response to your request does not contain any data,
• 400 Bad Request - the data sent by the client is not valid (a detailed description of the error is returned in message attribute),
• 401 Unauthorized - unauthorised access, missing or incorrect client_id,
• 404 Not Found - requested data not found,
• 500 Internal Server Error - An internal server error is caused, for example, by unavailable access to one of the system interfaces (database, web services, SAP, etc.).

API functions

Functions API are called by appropriate methods HTTP:

• GET returns data about the object, does not make any changes,
• POST sends a new data object,
• PUT updates an existing data object,
• DELETE removes the data object.

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

• it is necessary to add the Energy Label image to the media in the 3rd-4th position, the Information Sheet image and add the elements energy_label/information_list = true/false and switch=false
• fill in the ENERGY_CLASS parameter
• check that all product texts (descriptions / name) contain the correct information

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

• Brands (brands) - List of available brands.
• Category - List of available categories, product parameters available for these categories and, if applicable, available values of these parameters and the MENU MALL/MIMOVRSTE tree.
  The necessary data can also be found in the MALL Partner Portal in the section Category.
  For a more detailed description of the categories, sorting parameters and their values, see the article here.
• Transport (transport) - List of carriers that are based on the MALL side and their detail. The partner "selects" the carriers to use from this list.
• Transport (deliveries) - Shipments created by the partner and sent back to MALL. Shipments sent by the partner will then be available in the shopping cart.
• Labels - Sheet of all available labels/stickers. The partner uses the labels in the context of sales promotion based on instructions from MALL/MIMOVSRTE.
• Orders - All available order data. Includes listing of all orders, listing of basic data on all orders, order lists by different statuses, order detail, order update, order generation labels for MALL transport and others. For security reasons (to prevent the partner from sending unprepared orders), orders in the "blocked" status are deliberately removed from certain listings and must be called separately. Changes to orders can be tracked using the webhook.
• Products - Creating, editing and deleting partner products. Includes listing all products, listing basic data about all products, creating new products, activating "draft" products, updating product availability and pricing, and more.
• Variants - Similar to products, you can create, edit and delete variants of partner products.
• Verification - Data consistency verification. Options include verification of transports (deliveries) and media.
• Invoices - Lists and detail of invoices if the partner uses MALL Self-Billing. Invoice can be downloaded as a file.
• Credits - Lists and detail of credits if the partner uses MALL Self-Billing. The credit can be downloaded as a file.