Laredoute Offer Full update

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 page is to describe in details the process of full update of the offers on MIRAKL.

We are able to send updates to an offer using the call for creating an offer, but we need to specify the value in update_delete field to be equal to “update“ ( "update_delete": "update")

• POST OF01 - Import a file to add offers

API Call: /api/offers/imports

API Docs: https://laredoutestg-stg.mirakl.net/help/api-doc/seller/mmp.html#OF01

We will have to split the feeds into two. First case is to pick all products for full update with Protect Price = No this way we include all fields in the xml.

OR Product >EAN | Product Account > Marketplace EAN is with priority | | product-id-type | | | | Yes | hardcoded as “EAN“ | Must be UPPERCASE | | description | | | Offer description - Recommended - Maximum 2000 characters | No | Product Account > Description | | | internal-description | | | The description of the offer as shown in the back office view - Optional - Maximum 2000 characters | No | N/A | | | state | | | The state code of the offer The accepted values are defined from the Mirakl back office | Required | Product > Condition | Mapping to our conditions: 11- New > 1000; We need to include additional validation which return internal error if we select condition different from New “[INTERNAL]The item condition is incorrect. The only item condition allowed is New(with tags)!” | | price | | | The selling price in the currency. It is up to the operator to define with the seller whether the selling price includes or excludes taxes. Decimal number; a period is used to separate cents | Yes | Product Account > Start Price OR Product Account> RRP | we send Product Account > RRP If RRP is populated and is bigger than Price | | price-additional-info | | | Information regarding the price of the offer. Check with your operator if this information appears on the front. Character string limited to 100 characters | No | | | | quantity | | | The quantity available in stock (maximum: one billion). Integer greater than or equal to 0 | No | Product Account > Quantity | | | min-quantity-alert | | | | | N/A | | | eco-contributions | | | | | | | | | eco-contribution | | | | | | | | | producer-id | | No | Product Account Laredoute > Eco Producer Id | (v1.3)If empty we do not want to include it in the payload | | | | eco-contribution-amount | | No | Product Account Laredoute > Eco Contribution Amount | (v1.3)If empty we do not want to include it in the payload | | discount-price | | | | No | Product Account > Price | If RRP > Price

1. If there are discount dates imported in Hemi we use them

2. If there are no dates imported in Hemi we use the default dates (Now) and (Now + 2y) If RRP <= Price 3.We include the discount fields with empty values		discount-start-date				No	Product Account Laredoute > Discount Start Date	If RRP > Price andIf we do not specify any dates in the relevant fields we hardcoded current date (“NOW“) otherwise we use the date from the mapped field Date format - 2017-02-20T10:45:53+01 If RRP <= Price We include the discount fields with empty values		discount-end-date				No	Product Account Laredoute > Discount End Date	If RRP > Price and If we do not specify any dates in the relevant fields we hardcode current date + 2 year (“NOW“ +2y) otherwise we use the date from the mapped field Date format - 2017-02-20T10:45:53+01 If RRP <= Price We include the discount fields with empty values		leadtime-to-ship				No	Product Account > Dispatch Time Max OR Shipping Template >Dispatch Time Max	<v1.3>Product Account > Dispatch Time Max is with priority. If we have Product Account > Shipping Template we get the Dispatch Time Max from the Shipping Template If we do not have set Product Account > Shipping Template and we have Default Shipping Template set we get the Dispatch Time Max from the default Shipping Template else we do not push anything.</v1.3>		update-delete			Used only in "Normal" import mode. Update mode is used if blank. "", "update", "delete"	No	N/A			offer-additional-fields									offer-additional-field									code	vat	Yes	“vat“	<v1.3>Hardcoded as “vat“</v1.3>				value		Yes	Product Account > VAT OR Account > VAT	<v1.3>Product Account > VAT is with priority Available values: 20, 10, 5.5, 2.1 We need to make sure we are using only VAT% of the possible values </v1.3> <v1.4> The vat values should be with dot instead of comma </v1.4>
   	offer-additional-field					<v1.3>
   		code	rcp	No		<v1.3>Hardcoded as “rcp“</v1.3>
   		value		No	Product Account Laredoute > RCP
   	offer-additional-field
   		code	ecotax	No		<v1.3>Hardcoded as “ecotax“</v1.3>
   		value		No	Product Account Laredoute > Eco Tax

Second case is to pick all products for full update with Protect Price = Yes this way we exclude all price fields from the xml.

OR Product >EAN | Product Account > Marketplace EAN is with priority | | product-id-type | | | | Yes | hardcoded as “EAN“ | Must be UPPERCASE | | description | | | Offer description - Recommended - Maximum 2000 characters | No | Product Account > Description | | | internal-description | | | The description of the offer as shown in the back office view - Optional - Maximum 2000 characters | No | N/A | | | quantity | | | The quantity available in stock (maximum: one billion). Integer greater than or equal to 0 | No | Product Account > Quantity | | | leadtime-to-ship | | | | No | Product Account > Dispatch Time Max OR Shipping Template >Dispatch Time Max | <v1.3>Product Account > Dispatch Time Max is with priority. If we have Product Account > Shipping Template we get the Dispatch Time Max from the Shipping Template If we do not have set Product Account > Shipping Template and we have Default Shipping Template set we get the Dispatch Time Max from the default Shipping Template else we do not push anything.</v1.3> | | min-quantity-alert | | | | | N/A | | | state | | | The state code of the offer The accepted values are defined from the Mirakl back office | Required | Product > Condition | Mapping to our conditions: 11- New > 1000; We need to include additional validation which return internal error if we select condition different from New “[INTERNAL]The item condition is incorrect. The only item condition allowed is New(with tags)!” | | available-start-date | | | The first day the offer becomes available. The offer has no start date if blank.

yyyy-MM-dd or

yyyy-MM-ddThh:mm:ss+00   | No | N/A | | | available-end-date | | | The last day the offer is available. The offer has no end date if blank.

yyyy-MM-dd or

yyyy-MM-ddThh:mm:ss+00 | No | N/A | | | leadtime-to-ship | | | | No | Product Account > Dispatch Time Max OR Shipping Template >Dispatch Time Max | <v1.3>Product Account > Dispatch Time Max is with priority. If we have Product Account > Shipping Template we get the Dispatch Time Max from the Shipping Template If we do not have set Product Account > Shipping Template and we have Default Shipping Template set we get the Dispatch Time Max from the default Shipping Template else we do not push anything.</v1.3> | | update-delete | | | Used only in "Normal" import mode. Update mode is used if blank. "", "update", "delete" | No | N/A | | | offer-additional-fields | | | | | | | | | offer-additional-field | | | | | | | | | code | vat | Yes | “vat“ | <v1.3>Hardcoded as “vat“</v1.3> | | | | value | | Yes | Product Account > VAT OR Account > VAT | <v1.3>Product Account > VAT is with priority Available values: 20, 10, 5.5, 2.1 We need to make sure we are using only VAT% of the possible values

It seems the decimal values can only be sent as “2,1” (in other words - comma instead of a point) but as we aim to keep the fields uniform in Hemi I want this to happen after the info is selected from Hemi - meaning transform the “2.1” into “2,1” when sending. Same should be for all decimal values for the VAT field - select > Validate against currently set available values and if successful and the value is a decimal transform it to be with a comma</v1.3> | | | offer-additional-field | | | | | | | | | code | rcp | No | | <v1.3>Hardcoded as “rcp“</v1.3> | | | | value | | No | Product Account Laredoute > RCP | | | | offer-additional-field | | | | | | | | | code | ecotax | No | | <v1.3>Hardcoded as “ecotax“</v1.3> | | | | value | | No | Product Account Laredoute > Eco Tax | |

This is required because we either must have a feed with prices or a feed without prices otherwise MIRAKL will return an error.

We are able to send updates to products in 2 cases. Once the product listing status is Active and Inactive(i.e. after successfully zero stock updates)

We pick the offer for update when we have:

Product status **= Product Published ; Listing Status **= Active/Inactive; List/Update the whole item = Pending If we send the offer for update successfully we set: Product status **= Product Published ; Listing Status **= Active/Inactive; List/Update the whole item = Sent

Once we receive success, we need to set following statuses:

Product status = Product Published; **Listing Status =Active/Inactive; List/Update the whole item = Not Needed**

If we receive an error we will have:

Product status **= Product Published ; Listing Status **= Active/Inactive; List/Update the whole item = Error

(The error need to be stored into Update item error field.)

Example Response:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<offer_import_tracking>
    <import_id>2035</import_id>
    <product_import_id>2036</product_import_id>
</offer_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 OF02 - Get information and statistics about an offer import

API Call: /api/offers/imports/{import}

API Docs: https://laredoutestg-stg.mirakl.net/help/api-doc/seller/mmp.html#OF02

Using this call, we are able to check the status of the imported file.

Example Response:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<import>
    <date_created>2019-04-01T15:16:31Z</date_created>
    <error_report>false</error_report>
    <import_id>2035</import_id>
    <lines_in_error>0</lines_in_error>
    <lines_in_pending>0</lines_in_pending>
    <lines_in_success>1</lines_in_success>
    <lines_read>1</lines_read>
    <mode>NORMAL</mode>
    <offer_deleted>0</offer_deleted>
    <offer_inserted>1</offer_inserted>
    <offer_updated>0</offer_updated>
    <status>COMPLETE</status>
</import>

OF02 call is returning the response for the actual offer import (all offers).

Based on the response, we will need to check if we have to continue with the error report (if "error_report": true ) we continue with OF03, otherwise we treat it as success.

Success case:

Product status = Product Published and Listing Status = Active/Inactive and List/Update the whole item =Not Needed

Error case: If "error_report": true this means there is an error and we need to reach each of the reports in order to check for which item and what is the error.

Product status = Product Published ; Listing Status = Active/Inactive; List/Update the whole item = Error

and we need to store the relevant error in Product Account > Update Item Error field

• GET OF03 - Get the error report file for an offer import

In order to check if there are any errors related to the products, into imported file we should use the GET OF03 API Call.

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

API Docs: https://laredoutestg-stg.mirakl.net/help/api-doc/seller/mmp.html#OF03

"sku";"product-id";"product-id-type";"description";"internal-description";"price-additional-info";"quantity";"min-quantity-alert";"state";"available-start-date";"available-end-date";"logistic-class";"update-delete";"discount-start-date";"discount-end-date";"price";"discount-price";"discount-ranges";"price-ranges";"discount-start-date[channel=FR]";"discount-end-date[channel=FR]";"price[channel=FR]";"discount-price[channel=FR]";"discount-ranges[channel=FR]";"prices-ranges[channel=FR]";"discount-start-date[channel=CA]";"discount-end-date[channel=CA]";"price[channel=CA]";"discount-price[channel=CA]";"discount-ranges[channel=CA]";"prices-ranges[channel=CA]";"leadtime-to-ship";"error-line";"error-message"
"OFFER_SKU_004";"MKP100000000195360";"SKU";"My Offer Description n°1";"My Internal description 1";"My price Additional innformations";"1000000";"20";"11";"2017-02-20T10:45:53+01";"2017-04-30T10:45:53+01";"S";"update";"2017-02-22T10:45:53+01";"2017-04-30T10:45:53+01";"110.52";"108,56";"";"5|109.20,10|108.736";"2017-02-22T10:45:53+01";"2017-03-31T10:45:53+01";"105.56";"102,36";"";"5|104.56,10|103.27";"2017-02-22T10:45:53+01";"2017-03-31T10:45:53+01";"190.23";"175,36";"";"5|182.58,10|181.27";"15";"2";"The product does not exist"

As described above, this response give us detailed report of the SKUs and the actual SKUs errors are in the “error-message“  which we store in the Product Account >Update Item Error

Additional Information:

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

Protect Quantity (Stop all quantity updates) 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 the whole item - (Stop all product updates apart from Quantity)(v1.1)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

(v1.2) As this is an offer update (which includes Stock update as well) when we pick a Full Offer update for a product that has End Item on Pending the expectations are for the Stock to send 0 no matter of the different flags that might be preventing this