Item
#ItemController
Overview
Description
Path /v2/items
Handles all requests regarding items: creating, updating, deleting.
Item object
An example for a item json object.
Responses are usually wrapped in a meta object, which contains additional information about the response and may contain a single item or a list of items.
JSON Fields
width
height
depth
displayedWidth
displayedHeight
displayedDepth
perspectiveImage
perspectiveImageHD
topImage
assets : the known 3dAssets for this item.
configuration
hidden - deprecated - superseded by visibilityStatus
visibilityStatus : possible values
0 : SHOWN (visible everywhere)
1 : SHOWN_IN_CMS (visible only in cms context)
2 : ARCHIVED (hidden everywhere)
created
manufacturerSKU
updated
type
detailType
flipable
scaleable
colorable
layer
orderable
requestable
retailPriceAllowed
label
language
catalog
id
tags
affiliateIds
links
attributes
basecolor
version
CSV fields
id: identifier of an item (Deprecated)
item_id : identifier of an item
Translations can be multiple, we always return all the available translations in the form of multiple column pairs. If no translations are available, we insert in the CSV reference columns label_en and description_en.
label_{languageCode}: languageCode in ISO standard can be "en" or "de" for example and will be the current value of this language in the ItemTranslation.
description_{languageCode}: languageCode in ISO standard can be "en" or "de" for example and will be the current value of this language in the ItemTranslation.
type: for example "seating" or "table"
detailType: for example "sofa", "chair" or "table"
width: width of the item in millimeters
depth: depth of the item in millimeters
height: height of the item in millimeters
layer: can be an integer or null, if there is no value for this field
sort: can be an integer or null, if there is no value for this field
scaleable: indicates if the item is scalable or not
flipable: indicates if the item can be flipped or not
colorable: indicates if the item can be colored or not
hidden: indicates if the item is hidden
manufacturerSKU:
tag_ids: all tag ids separated by ' ' (whitespace)
configuration: the configuration of the item
visibilityStatus :
0 : SHOWN (visible everywhere)
1 : SHOWN_IN_CMS (visible only in cms context)
2 : ARCHIVED (hidden everywhere)
API Reference
GET /
Generates: json
Query item data based on given filters. If no filter is added by query parameters, all visible items for the requested user will be returned.
query-param:
deltaSince: has to be a date string with timezone. This string has to match following example
2016-06-01T07:54:07.000Z
. Only if given date string is matching this format, the response will be reduced to only updated items after given date.
Filter:
Each bullet point describes an available filter, where each secondary bullet point/s names the query parameter, which has to be added to the request in order to execute that filter correctly. If requirements for a filter are not met, then the request will behave like no filter was added and therefore will return all visible items.
all items for one catalog
catalog
all items for many catalogs
catalog[]
all items which are visible to the requested user and match types
types[]
specific items per id
ids[]
perfect fit items per item ids
perfectFitItemIds[]
perfect fit items per component ids
perfectFitComponentIds[]
similar items
type
detailType
color
width
depth
height
Response:
Item objects are described in Section Item JSON Object
GET /:id
Gets an existing Item.
Accepts: application/json
Generates: application/json
Response (200 OK): Item JSON Object
PUT /:id (json)
Updates an existing Item.
Accepts: application/json
Generates: application/json
Response (200 OK): Updated Item JSON Object
PUT /:id (multipart)
updates assets on an item
Accepts: multipart-formdata
Generates: application/json
parameters:
the data, either as file or as URL. if both are provided, an error is returned
file : datafile to be uploaded
fileUrl: the publicly available url to the datafile
type: type of the asset
possible types are
"perspectiveImage"
"perspectiveImageHD"
"topImage"
"glb_preview"
"src"
Response (200 OK): Item JSON Object
For more information on the assets, please check ElementAssets
DELETE /:id/:assetType
deletes assets on an item
possible types are images:
"perspectiveImage"
"perspectiveImageHD"
"topImage" 3d data:
"glb_preview"
Response (204 NO CONTENT): deleted
For more information on the assets, please check ElementAssets
GET /:id/topImage
returns a temporary redirect (307) to the URL of the topImage for this item
GET /:id/perspectiveImage
returns a temporary redirect (307) to the URL of the perspectiveImage for this item
GET /:id/perspectiveImageHD
returns a temporary redirect (307) to the URL of the perspectiveImageHD for this item
Uploading 3D Assets
You can upload 3D Assets for an item which will then be processed for realtime usage within the Roomle platform. If processed successfully, the dimensions of the 3D Asset will be taken as dimensions for the object, overriding any previously existing dimensions.
Asset Processing JSON object
An example for an asset processing object.
0
item
0
DAP received job
10
DAP is processing this job
100
DAP has successfully processed this job
-1
DAP had some kind of error while processing
GET /:id/threeDimensionalAssets
Generates: json
Returns all asset processing statuses for requested item
Response: Asset Processing objects are described in Section Asset Processing JSON Object
POST /:id/threeDimensionalAssets - DEPRECATED
since 2.41.3 - May 2024
use PUT /:id (multipart) instead
Requestinga a 3D Asset processing
POST /:id/renderings
Creating a new asset processing rendering job (DAP-job) for requested item.
Accepts: multipart-formdata
Generates: json
path-parameters:
id : item id
form-parameters: The form parameter body for rendering require the settings property to be present and views field of this property to be non-empty.
settings: contains all settings for import/render/export
POST /:id/3d-exports
Creating a new asset processing 3d-exports job (DAP-job) for requested item.
Accepts: multipart-formdata
Generates: json
path-parameters: -id : item id
form-parameters: The form parameter body for 3d-exports require the settings property to be present and the export field of this property to be non-empty.
settings: contains all settings for import/render/export.
POST /:id/assets - DEPRECATED
since 2.41.3 - May 2024
use PUT /:id (multipart) instead
POST /:id/conversions
Creating a new asset processing conversion job (DAP-job) targeting the item.
Accepts: multipart-formdata
Generates: json
path-parameters:
id : String - combinedId of the item where the results of the conversion will be saved, must be already created
form-parameters:
sourceId : String - combined id of the item that is the source of the conversion
type : String - identifier of the conversion type
settings: contains all settings for import/render/export/convert.
Settings json example:
Conversion types:
'static-to-configurable' : This conversion takes the source static item and converts it into a configurable item by creating materials, textures, meshes and components. The resulting component is then set as the target items root component, to achieve an immediately usable configurable item.
Last updated