Home > Webservices > Asynchronous products import

Asynchronous product import

Webservice URL : https://sws.spartoo.se/mp/xml_import_products_async.php

This webservice should be used in the same way as xml_import_products
The only difference with this webservice is that it integrates the products asynchronously.
When you click on this webservice, it returns a URL.
If you click on this URL, you will get the status of the file integration.

How it works

The asynchronous import works in two steps:

Feed submission: call the webservice with the xml parameter. The feed is queued and the webservice immediately responds with a URL (url tag) containing your import identifier (export parameter).
Tracking and result retrieval: call the webservice with the export parameter until you obtain the processing result (see the list of statuses below).

The feed can be sent in raw XML or compressed in ZIP format: the ZIP format is detected automatically.

List of Parameters

The settings of this webservice must be registered in POST

Settings	Description
partner	Must contain your unique code :
xml	XML character string containing the list of elements to be created or updated

Optional settings that can be passed in POST

Settings	Description
force_description	Set to 1 if you want to force product descriptions to be updated: delete existing descriptions, edit the description of a product with zero stock, etc.
force_overwrite	Set to 1 if you want to remove stock errors from the catalogue. Be careful to send the rest of the catalogue without overwriting immediately afterwards.
async	Set to 1 if you wish to use the asynchronous method

Parameter	Step	Description
xml	1	Product feed content (raw XML or ZIP). See formats below.
export	2	Import identifier, returned in step 1 in the response URL.

XML parameter format

The text fields must be protected by CDATA tags if they contain special characters that would make the XML invalid.

Format single country

<root>
	<products>
		<product>
			<reference_partenaire>string</reference_partenaire>
			<product_name>string</product_name>
			<manufacturers_name>string</manufacturers_name>
			<product_sex>char</product_sex>
			<product_price>float</product_price>
			<product_quantity>int</product_quantity>
			<color_id>int</color_id>
			<product_style>int</product_style>
			<product_description>string</product_description>
			<product_color>string</product_color>
			<heel_height>float</heel_height>
			<country_origin>int</country_origin>
			<code_hs>int</code_hs>
			<size_list>
				<size>
					<size_name>string</size_name>
					<size_quantity>int</size_quantity>
					<size_reference>string</size_reference>
					<ean>string</ean>
					<code_hs>int</code_hs>
					<product_price>float</product_price>
					<discount>
						<startdate>timestamp</startdate>
						<stopdate>timestamp</stopdate>
						<price_discount>float</price_discount>
						<rate>int</rate>
						<sales/>
					</discount>
				</size>
				<!-- ... Multiple "size" tags possible ... -->
			</size_list>
			<product_composition>int</product_composition>
			<voering_composition>int</voering_composition>
			<first_composition>int</first_composition>
			<zool_composition>int</zool_composition>
			<photos>
				<url1>url</url1>
				<url2>url</url2>
				<url3>url</url3>
				<url4>url</url4>
				<url5>url</url5>
				<url6>url</url6>
				<url7>url</url7>
				<url8>url</url8>
			</photos>
			<discount>
				<startdate>timestamp</startdate>
				<stopdate>timestamp</stopdate>
				<price_discount>float</price_discount>
				<rate>int</rate>
				<sales>0/1</sales>
			</discount>
			<extra_infos>
				<info>
					<id>int</id>
					<value>float</value>
				</info>
				<!-- ... Multiple "info" tags possible ... -->
			</extra_infos>
			<selections>
				<selection>int</selection>
				<!-- ... Multiple "selection" tags possible ... -->
			</selections>
		</product>
		<!-- ... Multiple "product" tags possible ... -->
	</products>
</root>

Format multi country

<root>
	<products>
		<product>
			<reference_partenaire>string</reference_partenaire>
			<manufacturers_name>string</manufacturers_name>
			<product_sex>char</product_sex>
			<product_quantity>int</product_quantity>
			<color_id>int</color_id>
			<product_style>int</product_style>
			<heel_height>float</heel_height>
			<country_origin>int</country_origin>
			<code_hs>int</code_hs>
			<languages>
				<language>
					<code>string</code>
					<product_name>string</product_name>
					<product_description>string</product_description>
					<product_color>string</product_color>
					<product_price>float</product_price>
					<discount>
						<startdate>timestamp</startdate>
						<stopdate>timestamp</stopdate>
						<price_discount>float</price_discount>
						<rate>int</rate>
						<sales />
					</discount>
				</language>
				<!-- ... Multiple "language" tags possible ... -->
			</languages>
			<size_list>
				<size>
					<size_name>string</size_name>
					<size_quantity>int</size_quantity>
					<size_reference>string</size_reference>
					<ean>string</ean>
					<code_hs>int</code_hs>
					<languages>
						<language>
							<code>string</code>
							<product_price>float</product_price>
							<discount>
								<startdate>timestamp</startdate>
								<stopdate>timestamp</stopdate>
								<price_discount>float</price_discount>
								<rate>int</rate>
								<sales/>
							</discount>
						</language>
						<!-- ... Multiple "language" tags possible ... -->
					</languages>
				</size>
				<!-- ... Multiple "size" tags possible ... -->
			</size_list>
			<product_composition>int</product_composition>
			<voering_composition>int</voering_composition>
			<first_composition>int</first_composition>
			<zool_composition>int</zool_composition>
			<photos>
				<url1>url</url1>
				<url2>url</url2>
				<url3>url</url3>
				<url4>url</url4>
				<url5>url</url5>
				<url6>url</url6>
				<url7>url</url7>
				<url8>url</url8>
			</photos>
			<extra_infos>
				<info>
					<id>int</id>
					<value>float</value>
				</info>
				<!-- ... Multiple "info" tags possible ... -->
			</extra_infos>
			 <selections>
				<selection>int</selection>
				<!-- ... Multiple "selection" tags possible ... -->
			</selections>
		</product>
		<!-- ... Multiple "product" tags possible ... -->
	</products>
</root>

Entry XML field description

Tag	Description	Required
reference_partenaire	Merchant product code. It is the sku that identifies a product of a brand in a precise color The product code may only contain alphanumeric characters as well as the following symbols: - (hyphen); _ (underscore); and . (full stop).	Yes
product_name	Style name Must not contain the category, colour, or brand of the product	No
manufacturers_name	Name of the product brand	Yes
product_sex	Product gender > See all possible values	Yes
product_price	Product price in euros (not compulsory for size prices)	Yes / Non
color_id	Colour for menu filters If the colour is not specified, the product will not show up if a customer uses the filter by colour > See all possible values	No
product_style	Product category > See all possible values	Yes
product_description	The product description allows you to include as much information as possible about the products, which can help customers make their purchasing decisions. A good product description is detailed and specific to each product. To that end, it may include the model name, brand, color, style, material, etc. You cannot insert HTML code, except for line breaks: , as well as , and . JavaScript is not allowed. It will be visible only on the product page. The maximum number of characters allowed is 65,000.	No
product_color	Text field for the colour. Appears on the product page.	No
product_quantity	Total stock of a product Ignore if one or more size_quantity markers are detected for the product. For one-size products, a product_quantity marker is necessary when the size_quantity is not given.	No
size	List of sizes and their stock. Optional for products with sizes (Bags/Accessories). Otherwise required.	Non / Oui
size_name	Size name > See all possible values	Yes
size_quantity	For each size, the number in stock must be specified. To deactivate a product, set the stock at 0. The product will then no longer appear on Spartoo.	Yes
size_reference	Reference of product size. This field is only used for the exporting of orders and returns. A good idea is to generate this reference by combining the fields reference_partenaire and size_name with an underscore "_".	No
ean	EAN of product size	No
photos	List of photos and their url. At least one photo is needed. However, we recommend a minimum of 3 photos. A maximum of 8 photos can be included. The photo will only be uploaded once, then stored on our servers once it has been resized to fit Spartoo dimensions. Photos must be in jpg format, square and a minimum of 500x500 pixels. If they are above or equal to 800x800 pixels, a zoom will be available on the site.	Yes
url1, url2 ... url8	Links to the photos You must provide one link per photo. Only alphanumeric characters and the characters "-" (dash), "_" (underscore) and"." (full stop) can be included in the file name. Spaces and accented letters (e.g. é, à, ñ) are not allowed.	Yes
heel_height	Heel height in centimetres (cm). Only for women's shoes. Must be a multiple of 0,5.	No
product_composition	Material of the product upper. Only for shoes. > See all possible values	No
voering_composition	Material of the product lining. Only for shoes. > See all possible values	No
first_composition	Material of the product insole. Only for shoes. > See all possible values	No
zool_composition	Material of the product outer sole. Only for shoes. > See all possible values	No
discount	Allows you to apply a promotion to a product or size. The field rate in the discount field applies to the discount by percentage with regards to the field product_price. The field price_discount in the discount concerns the discounted price of the fixed product. The discount percentage displayed will be calculated. If both fields are present, the price_discount field takes precedence over the rate field. If the discount is to start immediately, there's no need to fill in the field start date. If the stopdate field is not specified, the promotion will have a default duration of one month. If the field sales is specified, the offer will be a sales discount. Otherwise, it will be a standard offer. By defining this parameter, the item will appear on the sale page during the sales.	No
extra_infos	Specify additional information depending on the type of product. Each information is constituted by an id ( > See values ) and a numerical value.	No

XML parameter example

<root>
	<products>
		<product>
			<reference_partenaire>98</reference_partenaire>
			<product_name><![CDATA[ALL STAR HI]]></product_name>
			<manufacturers_name><![CDATA[Converse]]></manufacturers_name>
			<product_sex>M</product_sex>
			<product_price>64.99</product_price>
			<product_quantity>5</product_quantity>
			<color_id>8</color_id>
			<product_style>10010</product_style>
			<product_description><![CDATA[A legend among legends, the Chuck Taylor All Star from Converse is a classic!
Here you'll find the high-top version with a classic printed upper that gives them a stylish and classic look. 
]]></product_description>
			<product_color><![CDATA[Red]]></product_color>
			<country_origin>73</country_origin>
			<code_hs>64059090</code_hs>
			<size_list>
			 <size>
				<size_name>38</size_name>
				<size_quantity>4</size_quantity>
				<size_reference>98_38</size_reference>
				<ean>123456789011></ean>
			 </size>
			 <size>
				<size_name>39</size_name>
				<size_quantity>1</size_quantity>
				<size_reference>98_39</size_reference>
				<ean>123456789012></ean>
			 </size>
			</size_list>
			<product_composition>4</product_composition>
			<photos>
				<url1>https://imgext.spartoo.com/photos/98/98/98_350_A.jpg</url1>
				<url2>https://imgext.spartoo.com/photos/98/98/98_350_B.jpg</url2>
				<url3>https://imgext.spartoo.com/photos/98/98/98_350_C.jpg</url3>
				<url4>https://imgext.spartoo.com/photos/98/98/98_350_D.jpg</url4>
				<url5>https://imgext.spartoo.com/photos/98/98/98_350_E.jpg</url5>
				<url6>https://imgext.spartoo.com/photos/98/98/98_350_F.jpg</url6>
				<url7>https://imgext.spartoo.com/photos/98/98/98_350_G.jpg</url7>
				<url8>https://imgext.spartoo.com/photos/98/98/98_350_H.jpg</url8>
			</photos>
			<discount>
				<startdate>1199170800</startdate>
				<stopdate>1204354800</stopdate>
				<rate>20</rate>
			</discount>
		</product>
	</products>
</root>

Flow transfer via file

It is also possible to transfer the flow (XML or ZIP) via a file. To do this, the body of the request must contain only the file.
The various parameters (such as ‘partner’, “force_description”, ‘force_overwrite’, etc.) must be transmitted using GET.

Price and discount by size

Price and discount tags by size have been implemented to enable precise price differentiation within the same product.
They should only be used when a size has a price that differs from the general price of the product.
The price defined at the product level is the main reference. Size-specific tags are intended to override this price only when an exception is necessary (e.g., special sizes, additional material costs, partial end of line, etc.).
It is strictly prohibited to use price or discount tags by size when all sizes share the same price as the main product. In this case, the price must be defined only at the overall product level.

Multi-Country Format

In the multi-country format, the tag at the product level is required, even if prices are provided by size.
This tag defines the countries in which the product is offered for sale, as well as its name, description, and reference price (product_price) for each country. This price must be strictly positive.
The tags placed within the size entries are used solely to override this price for a given size and country. They are only taken into account for countries declared at the product level.
If the tag is missing at the product level, the feed is treated as a single-country feed: the price is then expected in the product’s tag. If it is missing, the product is rejected with error 7: “The price must be positive.”

Step 1 response: feed submission

XML format returned

<root>
	<url>string</url>
	<errors>int</errors>
</root>

Example:

<root>
	<url><![CDATA[https://sws.spartoo.com/mp/xml_import_products_async.php?partenaire=XXXX&export=123456]]></url>
	<errors>1</errors>
</root>

List of webservice error codes

Code	Description
1	No error with parameters
-1	The parameter partenaire has not been set up or it is empty
-2	The parameter partenaire does not exist
-11	The parameter xml has not been set up or it is empty
-15	XML syntax error, verify your XML file
-428	Your account has been deactivated. You will no longer have access to our online services.
-429	You have made too many online requests during this 1-hour time period.

XML response field description

This webservice return you the url to call to get back the webservice responses. If there was an error, it will be printed in a status markup. Otherwise, you will get an xml contening the import result.
This result will be the same format as xml_import_products. Below is the list of statuses returned by the webservice:

Status id	Status
1	Fichier pas encore traité
2	Aucune difference trouvé dans le fichier transferé
3	Resultat plus disponible
4	Erreur lors du transfert de fichier

Step 2 response: processing tracking

While the processing is not yet complete, the webservice returns a status:

<root>
	<status_id>int</status_id>
	<status>string</status>
	<errors>int</errors>
</root>

status_id	status	Meaning
1	Not Update Yet	The feed is pending or currently being processed. Please try again later.
2	No change found in file transfered.	Processing complete: no changes detected in the feed.
3	Result not available anymore	The feed has been processed but the result file is no longer available.
4	Error on file transfert	The feed could not be read: please resend it.
4	Skipped cause newer file found	Feed ignored as a more recent feed has been sent.

When processing is complete, the webservice returns the result file directly: it has the same format as the output of the classic import (see below).

Result format

<root>
	<products>
		<product>
			<reference_partenaire>string</reference_partenaire>
			<status>string</status>
			<action>string</action>
			<errors>
				<error>
					<id>int</id>
					<description>string</description>
					<level>string</level>
				</error>
				<!-- ... Multiple "error" tags possible ... -->
			</errors>
		</product>
		<!-- ... Multiple "product" tags possible ... -->
	</products>
	<errors>int</errors>
</root>

Tag	Description
reference_partenaire	Merchant product code
status	OK if the product is registered in database KO if the product has not been registered
action	List of possible actions : created: the product was created. not created: the product was not created. Note: a product can have a status 'OK' but not have been created after some 'Warning'. updated: the product was updated. not updated: the product was not updated. Note : a product can have a status 'OK' but not have been updated after some 'Warning'.
errors	List of processing errors: id : Product error code level: error level Warning: does not block product integration Fatal: blocks product integration description: error text description

List of product error codes

Code	Level	Description
1	Fatal	Referensnumret partner är för kort
2	Fatal	Partnerreferensen stämmer inte, den ska bara innehålla alfanumeriska tecken
3	Warning	Artikelns namn saknas
4	Fatal	Inget märke är angivet
5	Fatal	Kön är inte rätt angett, endast följande val är möjliga: H, F, M, K, G och B
6	Fatal	Priset ska vara i siffror
7	Fatal	Priset är negativt eller ej angett
8	Warning	Priset verkar för stort ( > 9000 kr)
195	Fatal	Det nya priset kan inte innehålla mer än xxx siffror
81	Fatal	Priset får ej överstiga 180€
9	Fatal	Kvantiteten ska vara ett heltal
10	Fatal	Kvantiteten måste vara ett positivt tal
11	Warning	Färgen xxx existerar inte: artikeln kommer inte gå att söka via färgfiltren
13	Fatal	Kategorin xxx existerar inte
14	Warning	Produktbeskrivning saknas
15	Warning	Färgbeskrivning saknas
16	Warning	Ingen lista med storlekar: använd one size
17	Warning	Kompositionen är angiven men inte rätt
18	Fatal	Foto nr 1 är obligatoriskt
19	Warning	Rabatten kommer inte att visas - procentsatsen för rabatten ska ligga mellan 0 och 100
20	Warning	Storleken xxx existerar inte
200	Warning	Storleken xxx finns inte för varumärket xxx.
201	Fatal	EAN-kod krävs
202	Fatal	EAN-koden xxx på produktreferensen xxx i storlek xxx används redan i referensen : xxx.
205	Fatal	Partnerreferensen är för lång
23	Warning	Fotot xxx är i mindre format än 350x350 och kvaliteten blir dålig på sajten
24	Warning	Fotot xxx är i mindre format än 350x350 och kan inte visas på sajten
25	Fatal	Storlek xxx: Omöjligt att följa upp och kontrollera lagersaldot
26	Fatal	Ej lagerförd: artikeln skapas inte
27	Fatal	Ingen åtkomst för foto nr 1: xxx ( url xxx )
28	Warning	Ingen åtkomst för detta foto: xxx ( url xxx )
30	Fatal	Antalet artiklar i storlek xxx är för stort (Maximalt antal: xxx)
33	Fatal	En produkt för xxx kan inte läggas in kategorin xxx
34	Fatal	Ordet xxx är blockerat och bör inte finns med i produktnamnet eler beskrivningen av produkten.
35	Fatal	Produktnamnet är för långt, det här fältet ska endast innehålla namnet på modellen. Felet/felen gäller för landet/länderna: xxx
341	Fatal	Ordet xxx är blockerat och bör inte finns med i produktbeskrivningen.
36	Fatal	Det går inte att importera produkten: produkten har en dubblering av storlek / färgpar.
37	Fatal	Du har inte angett giltig språkinformation för den här produkten för en aktiv internetsida
32	Fatal	Ingen information har hittats för detta land
38	Fatal	Storleken xxx kan bara användas en gång för produktreferensen xxx
39	Warning	Partnerreferensen finns flera gånger i flödet, dubbletter har ignorerats.
451	Fatal	Inget pris för storlek xxx i land xxx. (krävs för rabatt)
452	Warning	Slutdatum för den rabatt som överskrids för storleken xxx i landet xxx.
453	Fatal	"rate" (xxx) ogiltig för landets storlek xxx xxx.
454	Fatal	"rate" (xxx) > 85% för landets storlek xxx xxx.
455	Warning	Storleken xxx har ett pris på ett land (xxx) som inte är definierat för produkten.
456	Warning	Storlek xxx har ett pris på xxx som är identiskt med det globala priset på detta land.
194	Fatal	Sänkningen på priset får inte vara mer än xxx%

XML return examples

Example of a response to a web service request KO :

<root>
	<products></products>
	<errors>-1</errors>
</root>

Example of a response to a web service request OK :

<root>
	<products>
		<product>
		<reference_partenaire>EEAJBCC</reference_partenaire>
		<status>KO</status>
		<action>not created</action>
		<errors>
			<error>
				<id>14</id>
				<description>Produktbeskrivning saknas</description>
				<level>warning</level>
			</error>
			<error>
				<id>4</id>
				<description>Inget märke är angivet</description>
				<level>fatal</level>
			</error>
		</errors>
		</product>
		<product>
			<reference_partenaire>KJHGFDS</reference_partenaire>
			<status>OK</status>
			<action>created</action>
		</product>
	</products>
	<errors>1</errors>
</root>

Files XSD

Files XSD Multiple countries

Saitoo Marketplace

Bonjour ! Comment puis-je vous aider aujourd'hui ?