Yoox 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)

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 VARIANT_GROUP_CODE So we can add variants to a variation group only by specifying the correct VARIANT_GROUP_CODE If we want to remove a product from a variation we need to push the product for update again without the VARIANT_GROUP_CODE

• POST P41 - Import products to the operator information system

API Call: /api/products/imports

API Docs: https://richemontit3-dev.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 "has_error_report" and "has_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 Yoox integration we will go for the first option so we won’t need to make P31

If we receive an error (any of "has_error_report" and "has_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.

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:

T25255-FOOTWEAR-Trainers-example.xml

<import>
  <products>
    <product>
      <attribute>
        <code>CATEGORY</code>
        <value>T25255-FOOTWEAR-Trainers</value>
      </attribute>
      <attribute>
        <code>SHOP_SKU</code>
        <value/>
      </attribute>
      <attribute>
        <code>TITLE</code>
        <value/>
      </attribute>
      <attribute>
        <code>MF</code>
        <value>DA0983-100</value>
      </attribute>
      <attribute>
        <code>MODELCOLOR</code>
        <value>922</value>
      </attribute>
      <attribute>
        <code>EAN</code>
        <value/>
      </attribute>
      <attribute>
        <code>VARIANT_GROUP_CODE</code>
        <value/>
      </attribute>
      <attribute>
        <code>GENDER</code>
        <value>Unisex</value>
      </attribute>
      <attribute>
        <code>MADEIN</code>
        <value>Italy</value>
      </attribute>
      <attribute>
        <code>BRAND</code>
        <value>ARMANI</value>
      </attribute>
      <attribute>
        <code>FILTER_COLOR</code>
        <value>YELLOW</value>
      </attribute>
      <attribute>
        <code>MAT1</code>
        <value>Cotton</value>
      </attribute>
      <attribute>
        <code>MAT1PERC</code>
        <value>60</value>
      </attribute>
      <attribute>
        <code>MAT2</code>
        <value>Polyster</value>
      </attribute>
      <attribute>
        <code>MAT2PERC</code>
        <value>20</value>
      </attribute>
      <attribute>
        <code>MAT3</code>
        <value>Silk</value>
      </attribute>
      <attribute>
        <code>MAT3PERC</code>
        <value>10</value>
      </attribute>
      <attribute>
        <code>MAT4</code>
        <value>Viscose</value>
      </attribute>
      <attribute>
        <code>MAT4PERC</code>
        <value>5</value>
      </attribute>
      <attribute>
        <code>MAT5</code>
        <value>Leather</value>
      </attribute>
      <attribute>
        <code>MAT5PERC</code>
        <value>5</value>
      </attribute>
      <attribute>
        <code>ITEM_DESCRIPTION_ENG</code>
        <value/>
      </attribute>
      <attribute>
        <code>ITEM_DESCRIPTION_ITA</code>
        <value/>
      </attribute>
      <attribute>
        <code>FIRST_IMAGE</code>
        <value/>
      </attribute>
      <attribute>
        <code>SECOND_IMAGE</code>
        <value/>
      </attribute>
      <attribute>
        <code>THIRD_IMAGE</code>
        <value/>
      </attribute>
      <attribute>
        <code>FOURTH_IMAGE</code>
        <value/>
      </attribute>
      <attribute>
        <code>FIFTH_IMAGE</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIXTH_IMAGE</code>
        <value/>
      </attribute>
      <attribute>
        <code>MODEL_TITLE</code>
        <value>Air Max</value>
      </attribute>
      <attribute>
        <code>ITEM_DESCRIPTION_FR</code>
        <value/>
      </attribute>
      <attribute>
        <code>ITEM_DESCRIPTION_ES</code>
        <value/>
      </attribute>
      <attribute>
        <code>ITEM_DESCRIPTION_DE</code>
        <value/>
      </attribute>
      <attribute>
        <code>ITEM_DESCRIPTION_GR</code>
        <value/>
      </attribute>
      <attribute>
        <code>HCAT_492</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_108</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_6</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_507</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_506</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_479</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_92</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_98</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_477</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_473</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_518</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_519</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_395</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_101</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_502</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_404</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_466</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_700</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_124</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_530</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_40</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_403</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_406</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_407</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_408</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_411</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_412</code>
        <value/>
      </attribute>
      <attribute>
        <code>CAT_727</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_968</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_1075</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_1085</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_1137</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_1138</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_1140</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_1142</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_1179</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_1180</code>
        <value/>
      </attribute>
      <attribute>
        <code>SIZE_1222</code>
        <value/>
      </attribute>
      <attribute>
        <code>PREOWNED_CONDITION</code>
        <value>Brand New</value>
      </attribute>
      <attribute>
        <code>MIS_6</code>
        <value/>
      </attribute>
      <attribute>
        <code>MIS_7</code>
        <value/>
      </attribute>
      <attribute>
        <code>MIS_10</code>
        <value/>
      </attribute>
      <attribute>
        <code>MIS_34</code>
        <value/>
      </attribute>
      <attribute>
        <code>MIS_117</code>
        <value/>
      </attribute>
    </product>
  </products>
</import>

Mapping: Please note N/A means we exclude it from the payload.

OR Product > EAN | Product Account > Marketplace EAN is with priority | | VARIANT_GROUP_CODE | Code to group all variants of a product | Yes | Product Account > Variation Group | | | GENDER | Gender | Yes | Product Account > Item Specifics | | | MADEIN | Country where the product is made | No | Product Account > Item Specifics | | | BRAND | Brand of the product | Yes | Product Account> Item specifics OR Product > Brand | Product Account > Item Specifics is with priority | | FILTER_COLOR | The color visible to the final customer on PDP and used for filters | Yes | Product Account > Item Specifics | Yoox Specifics. | | MAT1 | The material that is present in highest percentage | Yes | Product Account > Item Specifics | Yoox Specifics. | | MAT1PERC | % of the material | No | Product Account > Item Specifics | Yoox Specifics. | | MAT2 | Material composition-2 | No | Product Account > Item Specifics | Yoox Specifics. | | MAT2PERC | % of the material | No | Product Account > Item Specifics | Yoox Specifics. | | MAT3 | Material composition-3 | No | Product Account > Item Specifics | Yoox Specifics. | | MAT3PERC | % of the material | No | Product Account > Item Specifics | Yoox Specifics. | | MAT4 | Material composition-4 | No | Product Account > Item Specifics | Yoox Specifics. | | MAT4PERC | % of the material | No | Product Account > Item Specifics | Yoox Specifics. | | MAT5 | Material composition-5 | No | Product Account > Item Specifics | Yoox Specifics. | | MAT5PERC | % of the material | No | Product Account > Item Specifics | Yoox Specifics. | | ITEM_DESCRIPTION_ENG | Product description in English | No | Product Account > Description | The description need to be mapped based on the channel language as follows: Benelux BE Central Europe CEUEastern Europe EEU Holland NL Scandinavia-Eire DK Southern Europe SEU | | ITEM_DESCRIPTION_ITA | Product description in Italian | No | Product Account > Description | The description need to be mapped based on the channel language as follows: Italy IT | | ITEM_DESCRIPTION_FR | Product description in French | No | Product Account > Description | The description need to be mapped based on the channel language as follows: France FR | | ITEM_DESCRIPTION_ES | Product description in Spanish | No | Product Account > Description | The description need to be mapped based on the channel language as follows: Spain ES | | ITEM_DESCRIPTION_DE | Product description in German | No | Product Account > Description | The description need to be mapped based on the channel language as follows: Germany DE | | ITEM_DESCRIPTION_GR | Product description in Greek | No | Product Account > Description | The description need to be mapped based on the channel language as follows: Greece GR | | MODEL_TITLE | The model as defined from the brand | No | Product Account Yoox > Model TItle | Yoox Specifics. | | FIRST_IMAGE | Primary image of the product | Yes | Product > Main Image OR Product Account Yoox > Main Image | Product Account Yoox is with priority New field. | | SECOND_IMAGE | Secondary image of the product | Yes | Product > More Picture URLs OR Product Account Yoox > More Images | Yoox Specifics. Product Account Yoox is with priority. New field. Please note in this case we would like to add a validation that the secondary image is required and More Images are required. | | THIRD_IMAGE | Additional product image | No | Product > More Picture URLs OR Product Account Yoox > More Images | Yoox Specifics. Product Account Yoox is with priority New field.. | | FOURTH_IMAGE | Additional product image | No | Product > More Picture URLs OR Product Account Yoox > More Images | Yoox Specifics. Product Account Yoox is with priority. New field. | | FIFTH_IMAGE | Additional product image | No | Product > More Picture URLs OR Product Account Yoox > More Images | Yoox Specifics. Product Account Yoox is with priority. New field. | | SIXTH_IMAGE | Additional product image | No | Product > More Picture URLs OR Product Account Yoox > More Images | Yoox Specifics. Product Account Yoox is with priority. New field. | | HCAT_492 | Is the product made of fur? made of fur (no shearling)? | Yes | Product Account Yoox > Made of Fur? | Yoox Specifics. New field. We want to add checkbox of 2 options: Yes and No. We need to map Yes to “made of fur” and No to “not made of fur”. Default selected option should be No |

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.

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://richemontit3-dev.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>
    <has_error_report>false</has_error_report>
    <has_new_product_report>false</has_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: "has_error_report" and "has_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 "has_error_report" and "has_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 "has_error_report" and "has_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 "has_error_report" and "has_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 has_error_report = true, into the response from P42;

API Call: API Call: /api/products/imports/{import}/error_report

API Docs: https://richemontit3-dev.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 has_transformation_error_report = true

API Call: /api/products/imports/{import}/transformation_error_report

API Docs: https://richemontit3-dev.mirakl.net/help/api-doc/seller/mmp.html#P47

Sample file -

5109-err.xml

• GET P31 - Get products for a list of product references

  API Call: /api/productsAPI Docs: https://richemontit3-dev.mirakl.net/help/api-doc/seller/mmp.html#P31

  Sample Request: API call: GET https://richemontit3-dev.mirakl.net/api/products?product_references=EAN|123456789

• We will be using the EAN in order to obtain the product Ids.

• Please note we can specify many product_references in single request like : https://richemontit3-dev.mirakl.net/api/products?product_references=EAN|123456789,EAN|1234567890123,EAN|1234567895123 etc.

  Samples Response:

  <?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
  <body>
      <total_count>1</total_count>
      <products>
          <product>
              <category_code>5110114</category_code>
              <category_label>Coffee Machines</category_label>
              <product_id>9312432012041</product_id>
              <product_id_type>EAN</product_id_type>
              <product_sku>MKP100000000037254</product_sku>
              <product_title>Breville Cafe Roma Stainless Espresso/Cappuccino Machine-ESP8C</product_title>
          </product>
      </products>
  </body>
  

  From the response we get the product_id and store it as Product Account > Channel Item ID.

Additional Information:

For this integration we will need to make sure the protect flags are working as expected:

Protect Quantity (Stop all quantity updates) - Applicable for already created offers. If the offer is not created this flag is ignored. If Protect Quantity = Yes and Update Quantity = Pending - We skip the product If Protect Quantity = Yes and Update Price= Pending - We pick the product only for price update and do NOT include the quantity in the payload If Protect Quantity = Yes and List/Update the Whole Item = Pending - We pick the product for full update but do NOT include the quantity in the payload

Protect Price (Stop all price updates) -Applicable for already created offers. If the offer is not created this flag is ignored. If Protect Price = Yes and Update Quantity = Pending -We pick the product only for stock update and do NOT include the prices in the payload If Protect Price = Yes and Update Price= Pending - We skip the product If Protect Price = Yes and List/Update the Whole Item = Pending - We pick the product for full update but do NOT include the prices in the payload

Protect the whole item - (Stop all product updates apart from Quantity) -Applicable for already created offers. If the offer is not created this flag is ignored. If Protect the whole item = Yes and Update Quantity = Pending -We send the quantity only If Protect the whole item = Yes and Update Price= Pending - We skip the product If Protect the whole item = Yes and List/Update the Whole Item = Pending - We skip the product

Closed -will stop all the updates to the MPs apart from the end item (send 0 stock update). This flag applies for all products the ones which are created and all new products.