WebService Calls > Basic Integration

Description

Create and update items.

For additional Growth options see also the full updateItems and the platform specific calls.

Request - Sample

Code

<mandator_id>1</mandator_id>

<identifier>Poloshirt/ L / White</identifier>

<internal_item_number>s4t_05-001</internal_item_number>

<vendor_item_number>HANR-s4t_05-001</vendor_item_number>

<ean_code>5901234123457</ean_code>

<tax_type_id>3</tax_type_id>

<weight_unit_id>400</weight_unit_id>

<volume_unit_id></volume_unit_id>

<piece_unit_id>500</piece_unit_id>

<base_price_type_id>5</base_price_type_id>

<external_category_id>[EXTERNAL_ID]</external_category_id>

<delivery_charge_category_id>147</delivery_charge_category_id>

<delivery_time_id>3029</delivery_time_id>

<vendor_id>38</vendor_id>

<is_adult_product>false</is_adult_product>

<upc_code>036000291452</upc_code>

<variant_parent_id>60</variant_parent_id>

<variant_standard>false</variant_standard>

<identifier>Color</identifier>

</property>

<value>

<identifier>White</identifier>

</value>

</attribute>

</attributes>

</variant>

<text_modules>

<text_module>

<text_module_type>15</text_module_type>

<language_code_iso>de</language_code_iso>

<text>Jederzeit passend gekleidet!! ... </text>

</translation>

</text_module>

</text_modules>

<image_modules>

<image_module>

<image_module_type_id>2627</image_module_type_id>

<image_url>https://www.speed4trade.com/image.png</image_url>

<is_local>true</is_local>

</image_module>

</image_modules>

<item_attributes>

<item_attribute significant_key="attribute_id">

<attribute_id>1323</attribute_id>

<attribute_identifier>Colour</attribute_identifier>

<attribute_data_type>STRING</attribute_data_type>

<attribute_value_type>FREE</attribute_value_type>

<item_attribute_values>

<item_attribute_value significant_key="attribute_value_identifier">

<attribute_value_identifier>Blue</attribute_value_identifier>

</item_attribute_value>

</item_attribute_values>

</item_attribute>

</item_attributes>

</item>

</request>

Request - Sample

Name	Description	Occ.	Type	Value Info
request	Root-Element of request	1	Element
method	Attribute of request. Name of Webservice-Method.	1	string	fixed value: „updateItems“
version	Attribute of request. Version control of request.	1	integer	fixed value: „1.0.0“
item	Wrapper-Element, summarizing the data of an item	0..N	Element
significant_key	Unique key to identify an item for updates	1	string	fixed values: „internal_item_ number“ \| „item_id“ \| „ean_code“ notes
mandator_id	client ID	1	integer
identifier	item identifier	1	string	length: 0-255 characters
internal_item_number	internal item number	1	string	length: 0-50 characters
vendor_item_number	manufacturer product number	0..1	string	length: 0-100 characters
ean_code	EAN-Code of item	0..1	string	length: 0-30 characters
tax_type_id	ID to identify used tax rate	1	integer	fixed values: 1 = tax free 2 = reduced 3 = normal
weight	weight of item	0..1	decimal
weight_unit_id	Unit of item weight; default: gramm	0..1	integer	fixed values
volume	Volume / capacity of item	0..1	decimal
volume_unit_id	Unit of item volume.	0..1	integer	fixed values
piece	number per P.U. (packing unit)	0..1	decimal
piece_unit_id	Unit ID for number per P.U. (packing unit)	0..1	integer	fixed values: ID = 500
base_price_type_id	Basic price type of item The basic price type required to set the related unit.	0..1	integer	fixed values
category_id	Group of goods-ID	0..1	integer	notes
external_category_id	External ID of group of goods	0..1	string	length: 0-50 characters notes
active	active / inactive	0..1	boolean	0 = cannot be used for offers
delivery_charge_category_id	id for delivery charge category this item belongs to	0..1	integer
external_delivery_charge_category_id	sets the id for delivery charge category via an external id	0..1	String	length: 0-100 characters
delivery_time_id	ID estimated delivery time	0..1	integer	notes
delivery_time_identifier	identifier of estimated delivery time	0..1	string	length: 0-255 characters notes
vendor_id	Manufacturer ID	0..1	integer
external_vendor_id	external manufacturer ID	0..1	string
is_adult_product	flag to identify for legal purposes, that this is an adult only product	0..1	boolean	default value: false
isbn	ISBN-Number of item	0..1	string	length: 0 – 13 characters
upc_code	UPC-Code of item	0..1	string	length: 0 – 12 characters
variant	Wrapper-Element, summarizing the information about item variations	0..1	Element
variant_parent_id	superior item id / parent id	1	integer
external_variant_parent_id	superior item id / parent id by external system	1	string	notes
variant_standard	identifies the standard variation of an item	0..1	boolean	notes
attributes	Wrapper-Element, summarizing the attributes of an variation	1	Element
attribute	Wrapper-Element, summarizing an attribute of the variation	1..N	Element
property	Wrapper-Element, summarizing the attribute characteristic of a variation	1	Element
identifier	identifies the attribute characteristic	1	string
value	Wrapper-Element, attribute values of an characteristic	1	Element
identifier	identifies the value of the characteristic	1	string
text_modules	Wrapper-Element, summarizing all text modules of an item	0..1	Element
text_module	Wrapper-Element, summarizing a single text module of an item	0..N	Element
text_module_type	ID of text module type	1	integer
translation	Wrapper-Element, summarizing all translations incl. the main language text of a text module	0..N	Element
language_code_iso	language of text	1	string	language code ISO 639-1 ALPHA-2 (e.g. „de“)
text	Text of text module type and language	1	string
image_modules	Wrapper-Element, summarizing all image information of item	0..1	Element
image_module	Wrapper-Element, summarizing the information of one item image	0..N	Element
image_module_type_id	ID of image module type	1	integer
image_url	URL were image is located	0..1	string	length: 0–200 characters
local_image_path	UNC path where image is located	0..1	string	notes
is_local	Is the local or URL image used?	1	boolean	1= local 0= not local
item_attributes	Wrapper-Element, which contains the attribute data	0..1	Element
item_attribute	Wrapper-Element, which contains the data of one attribute	1..N	Element
significant_key	Select the unique identifier type for this attribute	1	string	Fixed values: "attribute_id" \| "attribute_identifier"
attribute_id	The internal ID of the attribute	0..1	integer
attribute_identifier	Identifier of the attribute	0..1	string	notes max length: 100 characters
attribute_data_type	Datatype of the attribute	0..1	string	notes Fixed values: "STRING" \| "MULTILANGUAGE_STRING" \| "INTEGER" \| "DECIMAL" \| "BOOLEAN" \| "IMAGE_MODULE" \| "TEXT_MODULE" \| "MEDIUM" \| "FIELD_LINK"
attribute_value_type	Type of the attribute values	0..1	string	notes Fixed values: "FREE" \| "PRE_DEFINED"
item_attribute_values	Wrapper-Element, which contains the attribute values.	0..1	Element
item_attribute_value	Wrapper-Element, which contains the data of one attribute value.	1..N	Element
significant_key	Select the unique identifier type for this attribute value	1	string	Fixed values: "attribute_value_id" \| "attribute_value_identifier"
attribute_value_identifier	Identifier of the attribute value	0..1	string	Maximum length depending on the selected data type. Text = 100 characters; Integer = 10 digits; decimal = 7 digits left of the decimal point 2 digits right of the decimal point

Response - Sample

Code

Response Basic File List

Name	Description	Occ.	Type	Value Info
response	Root-element of response	1	Element
method	Attribute of response. Name of Webservice-Method.	1	string	fixed value: „updateItems“
version	Attribute of response. Version control of request.	1	integer	fixed value: „1.0.0“
report	Information about executed operation. A report element is returned for each requested item element.	0..N	Element
return_code	Attribute of report. Identifies error reason code.	1	integer	0 = OK. < 0 = error fixed values
error_description	Describes errors and error reasons of executed operation, once appeared.	0..1	string

Value Tables

Value Table - for Field: return_code

Value	Description
-1	Error
-4	Validation failed
-5	Access denied

Value Table - for Field: base_price_type_id

Value	Description
1	per 1 m
2	per 1 m²
3	per 100 cm³
4	per 1 dm³
5	per 100 g
6	per 1 kg
7	per 100 ml
8	per 1 l
9	per 1 piece \| Stück
10	per 1 m³

Value Table - for Field: language_code_iso.

Value	Description
de	German
en	English
fr	French
...

Value Table - for Field: volume_unit_id

Value	Description
300	mm³
305	cm³
310	dm³
315	m³
320	cu. in.
325	cu. ft.
330	cu. yd.
355	ml
357	cl
360	l
365	fl. oz.
370	pt.
375	qt.
380	gal.

Value Table - for Field: weight_unit_id

Value	Description
400	g
405	kg
407	t
409	oz.tr.
410	oz.
415	pd.

Value Table - for Field: piece_unit_id

Value	Description
500	piece \| Stück

Universal notes

•Each operation checks the availability of an entry fitting the significant key. If a fitting data record does exist, the call will update the data set. Otherwise a new data set is created.

•The elements category_id and external_category_id must not be used in combination.

•The elements delivery_time_id and delivery_time_identifier must not be used in combination.

•The elements default_shipping_carrier_id and default_shipping_carrier_identifier must not be used in combination.

•The element translation is already required for the first language. In other calls the element translation is just required for the 2..n language.

notes to "working with variations"

•The elements variant_parent_id and external_variant_parent_id must not be used in combination.

•When using the external_variant_parent_id, the parent item need to exist to make the assignment work.It is not possible to create the parent item and the child (variation) item in a single call, if variation items shall be linked together using the external_variant_parent_id.

•The standard variation characteristic "variant_standard" might be used only once within a parent-child variation set. There is no validation within Speed4Trade CONNECT . Marketplace and shops rely on a correct unique usage of this setting.

notes to "working with images"

•Using local_image_path, you must not use the linked network-drive letter. Use the UNC notation instead, since the services do not execute logon-scripts which link the drive to the drive letter.

notes to "working with item_attributes"

•When mixing central attributes with marketplace specific attributes, the central attribute will be used only.

•When creating a new attribute, data must be provided for attribute_identifier, attribute_data_type and attribute_value_type. To assign existing attributes to the item, it is sufficient to specify the attribute_id.

•Attribute values are set to override existing values for items. This means that in order to retain an existing attribute value assignment in the item and at the same time add another attribute value for the same attribute, both the existing and the new value must be transferred in the request.

•Best practice for attribute types:

oThe attribute type (attribute_value_type) should only be left at the default setting ‘PRE_DEFINED’ if only a few specific values are maintained for the attribute and if these are used as filter values on the sales channels. In all other cases, the attribute type should be changed to ‘FREE’, as this means that only one value per attribute is stored directly with the item (performance) and no value list needs to be stored and updated for the attribute.

oThe data type of the attribute (attribute_data_type) must always be selected according to the attribute usage. If the data type is not set, the default setting ‘MULTILANGUAGE_STRING’ is used. This then requires the transfer of elements ‘translations’ with at least one language. For other data types, the values are transferred in the ‘attribute_value_identifier’ field. The default setting should therefore only be used in cases where multilingual texts are actually to be stored as attributes.

oThe most commonly used combination is: attribute_data_type="STRING" and attribute_value_type="FREE".

•Important: For attributes that are used to create variants, please always pass the type attribute_value_type="PRE_DEFINED".

Changelog

Version	Change Description
4.8.46	Introduction of a Basic "Simplified" Integration