Laredoute Create Products
Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)
Date | Version | Name | Applied changes |
---|---|---|---|
06/03/2023 | v1.0 | Hristiyan | First Publish |
15/03/2023 | v1.1 | Hristiyan | Mapping changes |
10.05.2023 | v1.2 | Bogomil Pavlov | If Variation Group is empty we use the SKU |
The purpose of this document is to detailed describe the flow of creating product.
In order to create a product we will need to make couple of API Calls, which are POST P41 ( Import products to the operator information system), GET P42 (Get the import status for a product import) , GET P44 (Get the error report file for a product import), GET P47 (Get the transformation error report file for a product import)
How to handle variations in MIRAKL
The way we treat a product as a Variation is when we have Product Account > Variation Group populated. Each Product Account in Hemi can have Item Specifics and Variation Specifics which we validate the same way against the MIRAKL taxonomy but we use them only in certain cases.
If we DO NOT HAVE Product Account > Variation Group:
We use only the Item Specifics from the product if any Variation Specifics are also populated we ignore them
If we HAVE Product Account > Variation Group:
We use all of the Variation Specifics and all of the Item Specifics. If there are no Variation Specifics we should return an error. If we have the same attribute added as a Variation Specific and as a Item Specific we pick it only from the Variation Specifics.
Please note we do not need to select all variants if only one them is set for revision or creation because they goes as separate products on MIRAKL and the only thing which associate them is the ProductID
So we can add variants to a variation group only by specifying the correct ProductID
If we want to remove a product from a variation we need to push the product for update again without the ProductID
- POST P41 - Import products to the operator information system
API Call: /api/products/imports
API Docs: https://laredoutestg-stg.mirakl.net/help/api-doc/seller/mmp.html#P41
Complete flow:
In order to push products for creation we should have:
Product status = Awaiting Creation ; Listing Status **= Inactive; List/Update the whole item= Pending**
If we successfully pick a product for creation, we will have following statuses:
Product status -Awaiting Creation ; Listing Status - Inactive; List/Update the whole Item = Sent
If the internal product validation is not successful and we receive an error, we will set following statuses and store the relevant error message in Item Account > Update Item Error:
Product status = Awaiting Creation ; Listing Status=Inactive; List/Update the whole item= Error
If we receive success after performing P42 (when we send product to MIRAKL & When both "error_report"
and "transformation_error_report"
are equal to “false“ ) we can proceed to following:
Product status -Product Created ; Listing Status - Inactive; List/Update the whole Item = Pending
There will be two cases how to handle channel item ids in MIRAKL depends on the type :
- The first case is after successful product creation we need to fill the Channel Item ID, which will be the SKU.
- The second option is to use P31 Get products for a list of product references which will map the SKUs between Hemi and MIRAKL and store the MIRAKL id as Channel Item ID.
For Laredoute integration we will go for option 1
If we receive an error (any of "error_report"
and "transformation_error_report"
are equal to “true“):
Product status -Awaiting Creation ; Listing Status - Inactive; List/Update the whole Item = Error
And we need to store the relevant error message into the Product Account >Update Item Error.
Parameter | Notes | Required |
---|---|---|
File | Import file (CSV or XML or XLSX) to upload. Use multipart/form-data with name file |
Yes |
operator_format | Force the use of the operator product format | |
No |
Note: Every time we send products for creation we have to do internal check if all required attributes are part of the the product as Item Specifics or Variation Specifics according to their taxonomy which we download and store on the instance.
The file which we will import must be an xml file with the following structure:
Example File:
<?xml version='1.0' encoding='UTF-8'?>
<import>
<products>
<product>
<attribute>
<code>Product_Publication_ID</code>
<value/>
</attribute>
<attribute>
<code>Category</code>
<value>S1344</value>
</attribute>
<attribute>
<code>ShopSKU</code>
<value/>
</attribute>
<attribute>
<code>ProductTitle[fr_FR]</code>
<value/>
</attribute>
<attribute>
<code>EAN</code>
<value/>
</attribute>
<attribute>
<code>Brand</code>
<value/>
</attribute>
<attribute>
<code>ProductID</code>
<value/>
</attribute>
<attribute>
<code>ConceptNumber</code>
<value/>
</attribute>
<attribute>
<code>ClapID</code>
<value/>
</attribute>
<attribute>
<code>Product_Alt_Cod</code>
<value/>
</attribute>
<attribute>
<code>Description[fr_FR]</code>
<value/>
</attribute>
<attribute>
<code>ProductTitle[en_EN]</code>
<value/>
</attribute>
<attribute>
<code>Description[en_EN]</code>
<value/>
</attribute>
<attribute>
<code>Video</code>
<value/>
</attribute>
<attribute>
<code>Doc_installation_instructions</code>
<value/>
</attribute>
<attribute>
<code>Doc_reparability_index</code>
<value/>
</attribute>
<attribute>
<code>Master_Product_Main_Image</code>
<value/>
</attribute>
<attribute>
<code>Master_Product_Alternative_Image1</code>
<value/>
</attribute>
<attribute>
<code>Master_Product_Alternative_Image2</code>
<value/>
</attribute>
<attribute>
<code>Master_Product_Alternative_Image3</code>
<value/>
</attribute>
<attribute>
<code>Master_Product_Alternative_Image4</code>
<value/>
</attribute>
<attribute>
<code>Master_Product_Alternative_Image5</code>
<value/>
</attribute>
<attribute>
<code>Master_Product_Alternative_Image6</code>
<value/>
</attribute>
<attribute>
<code>Master_Product_Alternative_Image7</code>
<value/>
</attribute>
<attribute>
<code>Master_Product_Alternative_Image8</code>
<value/>
</attribute>
<attribute>
<code>Master_Product_Alternative_Image9</code>
<value/>
</attribute>
<attribute>
<code>Master_Product_Alternative_Image10</code>
<value/>
</attribute>
<attribute>
<code>Image1</code>
<value/>
</attribute>
<attribute>
<code>Image2</code>
<value/>
</attribute>
<attribute>
<code>Image3</code>
<value/>
</attribute>
<attribute>
<code>Image4</code>
<value/>
</attribute>
<attribute>
<code>Image5</code>
<value/>
</attribute>
<attribute>
<code>Image6</code>
<value/>
</attribute>
<attribute>
<code>Image7</code>
<value/>
</attribute>
<attribute>
<code>Image8</code>
<value/>
</attribute>
<attribute>
<code>Image9</code>
<value/>
</attribute>
<attribute>
<code>Image10</code>
<value/>
</attribute>
<attribute>
<code>Image11</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image01</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image02</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image03</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image04</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image05</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image06</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image07</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image08</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image09</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image10</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image11</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image12</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image13</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image14</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image15</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image16</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image17</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image18</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image19</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image20</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image21</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image22</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image23</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image24</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image25</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image26</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image27</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image28</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image29</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image30</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image31</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image32</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image33</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image34</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image35</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image36</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image37</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image38</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image39</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image40</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image41</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image42</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image43</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image44</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image45</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image46</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image47</code>
<value/>
</attribute>
<attribute>
<code>Animation_Image48</code>
<value/>
</attribute>
<attribute>
<code>360_Image01</code>
<value/>
</attribute>
<attribute>
<code>360_Image02</code>
<value/>
</attribute>
<attribute>
<code>360_Image03</code>
<value/>
</attribute>
<attribute>
<code>360_Image04</code>
<value/>
</attribute>
<attribute>
<code>360_Image05</code>
<value/>
</attribute>
<attribute>
<code>360_Image06</code>
<value/>
</attribute>
<attribute>
<code>360_Image07</code>
<value/>
</attribute>
<attribute>
<code>360_Image08</code>
<value/>
</attribute>
<attribute>
<code>360_Image09</code>
<value/>
</attribute>
<attribute>
<code>360_Image10</code>
<value/>
</attribute>
<attribute>
<code>360_Image11</code>
<value/>
</attribute>
<attribute>
<code>360_Image12</code>
<value/>
</attribute>
<attribute>
<code>360_Image13</code>
<value/>
</attribute>
<attribute>
<code>360_Image14</code>
<value/>
</attribute>
<attribute>
<code>360_Image15</code>
<value/>
</attribute>
<attribute>
<code>360_Image16</code>
<value/>
</attribute>
<attribute>
<code>360_Image17</code>
<value/>
</attribute>
<attribute>
<code>360_Image18</code>
<value/>
</attribute>
<attribute>
<code>360_Image19</code>
<value/>
</attribute>
<attribute>
<code>360_Image20</code>
<value/>
</attribute>
<attribute>
<code>360_Image21</code>
<value/>
</attribute>
<attribute>
<code>360_Image22</code>
<value/>
</attribute>
<attribute>
<code>360_Image23</code>
<value/>
</attribute>
<attribute>
<code>360_Image24</code>
<value/>
</attribute>
<attribute>
<code>360_Image25</code>
<value/>
</attribute>
<attribute>
<code>360_Image26</code>
<value/>
</attribute>
<attribute>
<code>Trigger_Synchro_Semarchy_TimeStamp</code>
<value/>
</attribute>
<attribute>
<code>Image_Dimensions</code>
<value/>
</attribute>
<attribute>
<code>Image_Energy_Label</code>
<value/>
</attribute>
<attribute>
<code>A0002</code>
<value/>
</attribute>
<attribute>
<code>A7415</code>
<value/>
</attribute>
<attribute>
<code>A2618</code>
<value/>
</attribute>
<attribute>
<code>A3115</code>
<value/>
</attribute>
<attribute>
<code>A1114</code>
<value/>
</attribute>
<attribute>
<code>A2596</code>
<value/>
</attribute>
<attribute>
<code>A3537</code>
<value/>
</attribute>
<attribute>
<code>A2599</code>
<value/>
</attribute>
<attribute>
<code>A3575</code>
<value/>
</attribute>
<attribute>
<code>A0001</code>
<value/>
</attribute>
<attribute>
<code>A2602</code>
<value/>
</attribute>
<attribute>
<code>A0485</code>
<value/>
</attribute>
<attribute>
<code>A3236</code>
<value/>
</attribute>
<attribute>
<code>A3195</code>
<value/>
</attribute>
<attribute>
<code>A2598</code>
<value/>
</attribute>
<attribute>
<code>A7435</code>
<value/>
</attribute>
<attribute>
<code>A3235</code>
<value/>
</attribute>
<attribute>
<code>A2617</code>
<value/>
</attribute>
<attribute>
<code>A2603</code>
<value/>
</attribute>
<attribute>
<code>A2604</code>
<value/>
</attribute>
<attribute>
<code>A2597</code>
<value/>
</attribute>
<attribute>
<code>A3775</code>
<value/>
</attribute>
<attribute>
<code>A3275</code>
<value/>
</attribute>
<attribute>
<code>A3135</code>
<value/>
</attribute>
<attribute>
<code>A2635</code>
<value/>
</attribute>
<attribute>
<code>A2600</code>
<value/>
</attribute>
<attribute>
<code>A2995</code>
<value/>
</attribute>
<attribute>
<code>A3576</code>
<value/>
</attribute>
<attribute>
<code>A2975</code>
<value/>
</attribute>
<attribute>
<code>A3295</code>
<value/>
</attribute>
<attribute>
<code>A2605</code>
<value/>
</attribute>
<attribute>
<code>A3895</code>
<value/>
</attribute>
<attribute>
<code>A8142</code>
<value/>
</attribute>
<attribute>
<code>A8195</code>
<value/>
</attribute>
<attribute>
<code>A8136</code>
<value/>
</attribute>
<attribute>
<code>A8155</code>
<value/>
</attribute>
<attribute>
<code>A8175</code>
<value/>
</attribute>
<attribute>
<code>A8137</code>
<value/>
</attribute>
<attribute>
<code>A8139</code>
<value/>
</attribute>
<attribute>
<code>A8138</code>
<value/>
</attribute>
<attribute>
<code>A8179</code>
<value/>
</attribute>
<attribute>
<code>A8140</code>
<value/>
</attribute>
<attribute>
<code>A8196</code>
<value/>
</attribute>
<attribute>
<code>A8141</code>
<value/>
</attribute>
<attribute>
<code>A8180</code>
<value/>
</attribute>
<attribute>
<code>A8181</code>
<value/>
</attribute>
<attribute>
<code>A8177</code>
<value/>
</attribute>
</product>
</products>
</import>
Mapping: Please note N/A means we exclude it from the payload.
Note: For LaRedoute some attributes are shown in the taxonomy but are only for internal use. We dont want to validate them against the taxonomy if required.
Product_Publication_ID
ConceptNumber
ClapID
Product_Alt_Cod
ProductTitle[en_EN]
Description[en_EN]
Video
Animation_Image01
Animation_Image02
Animation_Image03
Animation_Image04
Animation_Image05
Animation_Image06
Animation_Image07
Animation_Image08
Animation_Image09
Animation_Image10
Animation_Image11
Animation_Image12
Animation_Image13
Animation_Image14
Animation_Image15
Animation_Image16
Animation_Image17
Animation_Image18
Animation_Image19
Animation_Image20
Animation_Image21
Animation_Image22
Animation_Image23
Animation_Image24
Animation_Image25
Animation_Image26
Animation_Image27
Animation_Image28
Animation_Image29
Animation_Image30
Animation_Image31
Animation_Image32
Animation_Image33
Animation_Image34
Animation_Image35
Animation_Image36
Animation_Image37
Animation_Image38
Animation_Image39
Animation_Image40
Animation_Image41
Animation_Image42
Animation_Image43
Animation_Image44
Animation_Image45
Animation_Image46
Animation_Image47
Animation_Image48
360_Image01
360_Image02
360_Image03
360_Image04
360_Image05
360_Image06
360_Image07
360_Image08
360_Image09
360_Image10
360_Image11
360_Image12
360_Image13
360_Image14
360_Image15
360_Image16
360_Image17
360_Image18
360_Image19
360_Image20
360_Image21
360_Image22
360_Image23
360_Image24
360_Image25
360_Image26
Trigger_Synchro_Semarchy_TimeStamp
Image_Dimensions
Master_Product_Alternative_Image1
Master_Product_Alternative_Image2
Master_Product_Alternative_Image3
Master_Product_Alternative_Image4
Master_Product_Alternative_Image5
Master_Product_Alternative_Image6
Master_Product_Alternative_Image7
Master_Product_Alternative_Image8
Master_Product_Alternative_Image9
Master_Product_Alternative_Image10
The Images Mirakl considers images as attributes. La Redoute taxonomy has different kinds of images described below. Some image attributes available in the taxonomy are only for internal purpose and must not be pushed by vendors. Others like main image are mandatory or highly recommended (Master_Product_Main_Image or Image_2).
- Master_Product_Main_Image (OPTIONAL) : It is the image displayed in product list page. If not filled, the main image of an article will be picked from the product.
- Master_Product_Alternative_Image_1, Master Product Alternative Image 2, etc. (OPTIONAL) : Not displayed on front website. Should not be used.
- Main_image (MANDATORY) : Main article image.
- Image_2, Image_3, etc. (OPTIONAL) : Secondary article images (highly recommended).
- Animation_Image01, Animation_Image02, etc. (OPTIONAL) : Internal use only.
- 360_Image01, 360_Image02, etc. (OPTIONAL) : Internal use only.
- Image_Dimensions (OPTIONAL) : Internal use only.
Mirakl Field | Mirakl Notes | Integration Required | Hemi Field | Comment |
---|---|---|---|---|
Category |
Product category | Yes | Product Account > Primary Category ID | |
ShopSKU |
Shop article Sku | Yes | Product > SKU | |
ProductTitle[fr_FR] |
Product title | Yes | Product Account > Title | |
EAN |
Product EAN | Yes | Product Account > Marketplace EAN |
OR
Product > EAN | If we do not have EAN filled, we should display an error ( EAN is required and we could not proceed to product creation without EAN)
Product Account > Marketplace EAN is with priority |
| Brand
| Brand of the product | Yes | Product Account> Item specifics
OR
Product > Brand | Product Account > Item Specifics is with priority |
| ProductID
| Link between Variants of a same product | Yes | (v1.2)Product Account > Variation Group
OR
Product > SKU | (v1.2)As this field is mandatory we want to have a logic and if the Product Account > Variation Group is not populated and we are listing single product to get the Product > SKU |
| Description[fr_FR]
| Product description French | Yes | Product Account > Description | |
| Doc_installation_instructions | | No | Product Account> Item specifics | |
| Doc_reparability_index | | No | Product Account> Item specifics | |
| Master_Product_Main_Image | | No | Product > Listing Image | |
| Image1
| Main product image | Yes | Product > Main Image or Product Account LaRedoute > Main Image | |
| Image2
| More product images | No | Product > More Picture URLs or Product Account LaRedoute > More Images | |
| Image3
| More product images | No | Product > More Picture URLs or Product Account LaRedoute > More Images | |
| Image4
| More product images | No | Product > More Picture URLs or Product Account LaRedoute > More Images | |
| Image5
| More product images | No | Product > More Picture URLs or Product Account LaRedoute > More Images | |
| Image6
| More product images | No | Product > More Picture URLs or Product Account LaRedoute > More Images | |
| Image_Energy_Label | | | Product Account> Item specifics | |
Example Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<product_import_tracking>
<import_id>2035</import_id>
</product_import_tracking>
After each successfully send feed for creation we will receive the feed id from the response and need to store it in Marketplace Feeds table.
Mirakl Field | Hemi Field | Comment |
---|---|---|
import_id | Marketplace Feed > External ID | |
Marketplace Feed > Account | For which account is the feed generated. | |
Marketplace Feed > Type | Hardcoded as “Listing Create“ | |
Marketplace Feed > Submitted Date | When the feed is submitted | |
Marketplace Feed > Sent Objects Count | How many products we have pushed in the feed |
Please note we will also add the feed objects which after processing need to be removed.
- GET P42 -Get the import status for a product import
API Call: /api/products/imports/{import}
API Docs: https://laredoutestg-stg.mirakl.net/help/api-doc/seller/mmp.html#P42
Example response:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<product_import_tracking>
<import_id>2005</import_id>
<date_created>2019-04-05T12:56:21Z</date_created>
<error_report>false</error_report>
<new_product_report>false</new_product_report>
<has_transformation_error_report>false</has_transformation_error_report>
<has_transformed_file>true</has_transformed_file>
<import_status>SENT</import_status>
<shop_id>2000</shop_id>
<transform_lines_in_error>0</transform_lines_in_error>
<transform_lines_in_success>1</transform_lines_in_success>
<transform_lines_read>1</transform_lines_read>
<transform_lines_with_warning>0</transform_lines_with_warning>
</product_import_tracking>
Depends on the response of:
"error_report"
and "transformation_error_report"
we will need to call each of the error reports if we receive "true".
Also if we already have the item pushed into another feed from the same type we remove it from the objects (table 2511) and need to add it in the latest sent feed. Via this way we wont read any old or previous responses for the particular SKU.
When both "error_report"
and "transformation_error_report"
are equal to “false“ is the success case (Import status = Completed) and we could proceed to creating and offer to this product.
If we receive success (When both "error_report"
and "transformation_error_report"
are equal to “false“ ) we can proceed to following:
Product status -Product Created ; Listing Status - Inactive; List/Update the whole Item = Pending
If we receive an error (any of "error_report"
and "transformation_error_report"
are equal to “true“):
Product status -Awaiting Creation ; Listing Status - Inactive; List/Update the whole Item = Error
And we need to store the relevant error message into the Product Account >Update Item Error.
- GET P44 - Get the error report file for a product import
We need to perform this call if we receive error_report
= true, into the response from P42;
API Call: API Call: /api/products/imports/{import}/error_report
API Docs: https://laredoutestg-stg.mirakl.net/help/api-doc/seller/mmp.html#P44
Basically, we read the report and we extract the SKU column. After that we compare the Errors
columns and we need to store them.
Also, the record for the SKUs that have matched need to be removed from Marketplace Feed Object table.
We will consider Warning=Success in the integration (it is kind of standard on every MIRAKL)
Sample file
product-import-errors-file-20220929110013 (1).csv
- GET P47 - Get the transformation error report file for a product import
This call returns if the import is successful and how may warnings and errors we have in the file. We need to call this if we receive transformation_error_report
= true
API Call: /api/products/imports/{import}/transformation_error_report
API Docs: https://laredoutestg-stg.mirakl.net/help/api-doc/seller/mmp.html#P47
Sample file -
Additional Information:
For this integration we will need to make sure the protect flags are working as expected:
Closed -will stop all the creation of the products to the MPs.