(Quick Reference) Service: Upsert an item

Description: This web service is used to insert an item object to the database if it does not already exist, or update it.

URL with external_id:

https://BASE_URL/api/VERSION/items/reference/{id}

Method: POST

Request content type: application/x-www-form-urlencoded or multipart/form-data

Parameters:

NameDescriptionTypeRequiredExample values
reference Stringyes 
name Stringyes 
description Stringno 
categoryIdThe ID of the item category.String- 
isActiveBy default, it is set to trueBooleannotrue, false
isNew Booleannotrue, false
displayOrder Integerno 
volumeInLiter Doubleno1.5
pdfFilePdf size must be lower than 100 MBpdfno 
videoVideo size must be lower than 100 MBwebm, avi, mpeg , quicktimeno 
image1Image size should not exceed 2 MBjpg, gif, png, bmpno 
image2Image size should not exceed 2 MBjpg, gif, png, bmpno 
image3Image size should not exceed 2 MBjpg, gif, png, bmpno 
tagsTags should not contain comma seperatorJSON listno["bracelet","jewelry"]
similarItemsList of similar items idJSON listno[750,751]
hasSerialNumbersBy default, it is set to falseBooleannotrue, false
hasDeclinationBy default, it is set to falseBooleannotrue, false

By default, if the parameter itemCategoryId is not specified, item will be added to the root item category. It will be required if there is many root categories.

Declination parameters (optional):

Parameter name: attributeValues

Parameter type: a json structure

NameDescriptionTypeRequiredExample values
itemReference Stringyes 
attributeValueId Integeryes 

Example:

attributeValues=[{itemReference:"tshirt_BLEU_S",attributeValueId:16},{itemReference:"tshirt_BLEU_S",attributeValueId:7},
{itemReference:"tshirt_ROUGE_XL",attributeValueId:6},{itemReference:"tshirt_ROUGE_XL",attributeValueId:9}]

Success Output

Status: HTTP/1.1 201 Created

{
  "id": 706,
  "reference": "bracelet-GRP09062",
  "name": "Knot Band Bracelet",
  "description": null,
  "itemCategoryId": 2,
  "itemCategory": {
    "id": 2,
    "reference": "Ref-01",
    "name": "Jewelry",
    "href": "/api/v1.0/itemCategories/2"
  },
  "itemImages": null,
  "displayOrder": 1,
  "volumeInLiter": null,
  "isActive": false,
  "isNew": true,
  "videoUrl": "",
  "videoSize": 0,
  "formattedVideoSize": "0",
  "pdfUrl": "BASE_URL/entity1-1450169988465/itemPdfs/1471271200022_items_10_08_2016.pdf",
  "pdfSize": 124487,
  "formattedPdfSize": "121,6 Ko",
  "similarItems": [],
  "parentId": null,
  "parentItem": null,
  "hasDeclination": false,
  "relatedItems": [],
  "itemAttributes": [],
  "tags": [],
  "hasSerialNumbers": false,
  "serialNumbers": null,
  "organization": "entity1",
  "dateCreated": "2016-08-11T09:17:30Z",
  "lastUpdated": "2016-08-11T09:17:30Z"
}

Failure Output

Status: HTTP/1.1 400 Bad Request

{
  "error": "save_failed",
  "error_description": "Failed to save instance."
}

{
  "error": "not_unique",
  "error_description": "reference already used"
}

{
  "error": "missing_param",
  "error_description": "Name parameter is missing"
}

{
  "error": "exceeded_file_size",
  "error_description": "image size should not exceed 2Mo"
}

{
  "error": "unsupported_file_type",
  "error_description": "image format not supported."
}

Status: HTTP/1.1 404 Not Found

{
  "error": "not_found",
  "error_description": "The Item Category with the id 2452 doesn't exist."
}