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

API is built on REST architecture, which enables data access and creating operations such as data export, creating, editing or deleting subjects (products, delivery methods etc.).
API uses HTTPS security protocol.

These requests are sent to https://mpapi.mallgroup.com/in production environment, regardless of the country in which you will be selling the product.
The country is identified according to client_id.

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

All data are sent and returned in JSON and UTF-8 code format. The response for the given request will be in HTTP code, data and eventually paging in appropriate methods.

{ "result": { "code": 200/400/403/404/500, "status": OK/ERROR/LIMITED, "message": doplňující zpráva }, "paging": { "pages": počet stránek, "size": počet položek na stránce, "page": aktuální strana }, "data": { strukturovaná data } }

Detailed information about HTTP codes, paging and most importantly to prescribed data structure are available in the online documentation.

For quicker implementation MPAPI client is at your disposal (only in PHP, 5.5 and higher version is supported at the moment). Downloading and newest version information can be found at packagist.org/packages/mallgroup/mpapi-client.

Changelog

Online documentation contains all up to date information. Eventual changes are noted in the Changelog section including retention date.

API architecture

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

API endpoints

Alt text

1. Transparent proxy

  • You can use a transparent proxy for independent testing of the API (you can call modes from the online documentation Mock Server or Debugging Proxy),
  • You can track your transparent proxy requests by clicking on the Inspector link in the top menu.
  • If you will not use transparent proxy, you can send demands directly to URI endpoints in production environment

2. Production environment

Authorization

Every request must contain an authorization key (client id). This key is available in the partner portal.

Data format

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

Object identification

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

  • MALL does not issue any row numbers to partners
  • Identifiers can contain combinations of a maximum of 50 characters, allowed characters are: _, -, 0-9, a-z, A-Z (underscores, hyphens, numbers zero to nine, lowercase and uppercase letters without accents).
  • Identifier must be unique on partner level

Exceptions are for example orders, carriers or invoices. In case of orders MALL/MIMOVRSTE generates an order_id, which is then available in the v list of open orders. This number ID is used while working with the order.

Warning::
MALL order_id exceeds the maximum size allowed for 32 bite PHP version. To avoid inconsistent data in orders, please use to 64 bite version.

Output

The output is in this 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 don´t return any contents (code 204).

Result

Result gives a HTTP code, status and possible error message.

Paging

Object paging is used, if the output is divided into more pages.
Paging can be set by URL call with page and page_size parameters. The initial (and recommended maximum value) page size is 100.

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

Data

Data structure changes depending on the endpoint and is described in the online documentation for each endpoint separately.

HTTP status codes

  • 200 OK – everything is alright, data are successfully returned
  • 201 Created – the request has been fulfilled and has resulted in an entity being created
  • 204 No content – answer to your request does not contain any data
  • 400 Bad Request – sent data are not valid (detailed error description is retrieved with message attribute)
  • 401 Unauthorized – unauthorized access, missing or wrong client_id
  • 404 Not Found – requested data not found
  • 500 Internal Server Error – internal error happens when there is e.g. inaccessible approach to one of the system divisions (database, online service, SAP etc.)

API function

API functions are called using suitable HTTP methods:

  • GET returns object data, doesn´t do any changes,
  • POST sends new object data,
  • PUT updates existing object data,
  • DELETE erases object data.

Data validation

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

Optional parameters

If the character is optional and you do not want to use it, do not include it in the API request. If it is set with a blank value, an error message Key {key} does not exist or is empty will show.

Product images

To update a product / variant image, you'll need to change the image URL.
For example, by adding a parameter in the form TIMESTAMP or product/variant ID 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 for a product is 20. The maximum response time of an image URL is 1 s. Image URL must not contain spaces or accents.

Energy label

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 unintentional change in product price

There can be certain risks in situations, where the partner updates his products on different e-shops with different currencies.
Partner may send the product price in the wrong currency. To partially eliminate this risk, product price limit is set for protection.
The allowed price difference between the old and new price of the product/variant is 30 %.

A product with a significant price difference can therefore only be updated using force_token taken from a failed product update. In the next request it is necessary to send the obtained force_token as a URL parameter.

A product with a significant price difference can therefore only be updated on use force_token obtained from a failed product update. In the next request it is necessary to send the obtained force_token as a URL parameter.

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

By updating the price of the product with the help of force_token, the partner confirms that the new price is correct and that he takes full responsibility for this newly set price.
In these cases, caution is in place locally and should not be used force_token automatically. All changes and token usage are recorded by MALL.
In countries outside the CZ, use as an amount separator dot ".".

Example::

{"errorCodes": [{"message": "Difference between current price ({value of current price}) and new price ({value of new price}) for product" {product id} "is larger than 30% ({real 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 larger 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 – List of available brands.
  • Category - List of available categories, product parameters available for these categories and possibly available values of these parameters and the MENU MALL tree.
    You will also find the necessary data in the MALL Partner portal in the section Category.
    A more detailed description of categories, sorting parameters and their values can be found in the article here.
  • Transports – List of carriers that are based on MALL and their detail. Partner “selects” from this list the carrier that he will use.
  • Deliveries – Transportation established by partner and sent back to MALL. The transport sent by the partner will then be available in the shopping cart.
  • Labels – List of all available labels. Partner uses these labels as part of sales support based on an MALL / MIMOVSRTE guidelines.
  • Orders – All available order data. Contains a list of all orders, a list of basic data about all orders, list of orders according to statuses, order detail, order update, labels generated for MALL delivery and more. As part of security (prevention of sending unprepared orders by the partner), orders in the "blocked" status are intentionally removed from certain statements and must therefore be called separately. Changes to orders can be tracked using the webhook tool.
  • Partners – General information and partner settings. Contains settings supply delay at the level of the whole partner.
  • Products – Creating, editing and deleting partner products. It contains a list of all products, a list of basic data about all products, the creation of new products, the activation of "draft" products, the update of product availability and prices, and more.
  • Variants – As products, it is possible to create, edit and delete variants of partner products.
  • Checks – Verification of data consistency. The options include verification of deliveries and media.
  • Invoices – Lists and detail of invoices if the partner uses self-biling. Possibility to download the invoice as a file.
  • Credits – Lists and detail of credits if the partner uses self-biling. Possibility to download the credit as a file.

How useful was this post?

Click on the star to rate the post!

Average rating: / 5. Number of votes:

No votes yet! Be the first to rate this post.