VCloud API - Universal Item documentation

Introduction

Universal item file as for target to describe item in a unified way. This allows to easily exchange with external software, graphic template, ... It defined a lots of fields as price, allergens, stock, deposit, promotions, ...

All fields are grouped in different categories to be more simple to use. Each category is described in details further in the document. All categories are optional, so a store without fresh product didn't need to fill fresh fields and could totally ignore them. New category could be added in the future for new market.

Identifiers

3 fields are very important to understand to fully identified and retrieve items: id, domain, references.

Id is the unique key to identify an item, all items has an id and all id matches only one item.

The domain determines where the item is applied. In most of the case its a corporation and a store location as "Leclerc.Paris-6eme". It could be defined for a whole corporation as "Leclerc".

References is a list of code attached to the item. One item could have any count of references, and one reference could target one or more item.

InternalId

If back-office can't provide for each item an id and a list of references, you can use this special field to link different item. But that's not the preferred way.

Custom

If you need more fields, it is possible to add custom field into the custom category.

E.g: if you need to add specific information for wine.

         { 
                   "id": "210987654321", 
                   "domain": "nicolas.herblay", 
                   "name": "Red wine", 
                   "capacity": "0.75l", 
                   "custom": { 
                           "variety": "Cabernet Sauvignon", 
                           "appellation": "Bordeaux", 
                           "alcool": "13°" 
                    } 
         }

The item has to be readable by human and modified by them, so it is advised to not add computed fields into and keep those computation into the designer part. For example, avoid to add a custom field for the nameLength.

ISO8601

ISO8601 is the standard date format retains by VusionGroup for date processing.

We preconise to mainly used the format YYYY-MM-DD

The pattern for this item type is

^([\+-]?\d{4}(?!\d{2}\b))((-?)((0[1-9]|1[0-2])(\3([12]\d|0[1-9]|3[01]))?|W([0-4]\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\d|[12]\d{2}|3([0-5]\d|6[1-6])))([T\s]((([01]\d|2[0-3])((:?)[0-5]\d)?|24\:?00)([\.,]\d+(?!:))?)?(\17[0-5]\d([\.,]\d+)?)?([zZ]|([\+-])([01]\d|2[0-3]):?([0-5]\d)?)?)?)?$

Description

Category: standard

Description

Standard fields which are used in nearly all interfaces as name, price, unit price, currency, ...

Fields

Example of standard

      { 
               "id": "210987654321", 
               "domain": "corporationName.store", 
               "name": "Bread", 
               "price": 1.10, 
               "unitPriceUnit": "1kg", 
               "unitPrice": 2.20, 
               "currency": "$", 
               "capacity": "500g" 
       }

Example of standard with scheduled items

       { 
               "id": "210987654321", 
               "domain": "corporationName.store", 
               "name": "Bread", 
               "price": 1.10, 
               "unitPriceUnit": "1kg", 
               "unitPrice": 2.20, 
               "currency": "$", 
               "capacity": "500g", 
               "schedules":[{"schedule": "2022-12-08T09:15:00.000Z", "item":{"price": 10.52, "name": "changed name"}}] 
       }

Example of standard with scheduled refresh

       { 
               "id": "210987654321", 
               "domain": "corporationName.store", 
               "name": "Bread", 
               "price": 1.10, 
               "unitPriceUnit": "1kg", 
               "unitPrice": 2.20, 
               "currency": "$", 
               "capacity": "500g", 
               "refreshSchedules": ["2022-12-02T13:27:00.218Z"] 
       }

Category: promotion

Description

Promotions contains fields relative to promotion information.

Fields

Example of promotion

{
	"id": "210987654321",
	"domain": "corporationName.store",
	"name": "Bread",
	"price": 0.55,
	"unitPriceUnit": "1kg",
	"unitPrice": 1.1,
	"currency": "$",
	"capacity": "500g",
	"inPromotion": true,
	"promotion": {
		"discountRate": "-50%",
		"regularPrice": 1.1,
		"perUnitPrice": 2.2,
		"start": "2016-01-15",
		"end": "2016-05-01"
	}
}

Category: management

Description

Contains stock, sell statistics, facing, order, ... All informations relative for worker in the shop and not the customer.

Fields

Example of management

{
	"id": "210987654321",
	"domain": "corporationName.store",
	"name": "Bread",
	"price": 5.5,
	"unitPriceUnit": "1kg",
	"unitPrice": 11.0,
	"currency": "$",
	"capacity": "500g",
	"facing": 2,
	"margin": {
		"recommendedPrice": 5.5
	},
	"order": {
		"automatic": false,
		"available": true,
		"deliveryDays": [
			"MONDAY",
			"TUESDAY",
			"THURSDAY",
			"FRIDAY"
		],
		"nextDelivery": "2016-01-18",
		"quantity": 45
	},
	"sellStatistics": {
		"last7Days": 487,
		"perMonth": 2471
	},
	"stock": {
		"current": 88,
		"level": "GOOD",
		"minimum": 20,
		"unit": "piece"
	}
}

Category: fresh

Description

Fresh contains fields which is generally used for fresh products as vegetables, fruits or flowers.

Fields

Example of fresh

{
	"id": "210987654321",
	"domain": "corporationName.store",
	"name": "Apple Granny Smith",
	"price": 1.75,
	"unitPriceUnit": "1kg",
	"unitPrice": 1.75,
	"currency": "$",
	"capacity": "1kg",
	"fresh": {
		"origin": "France",
		"caliber": "I",
		"originCode": "33",
		"variety": "Granny Smith",
		"treatments": [
			"Antimicrobial"
		]
	}
}

Category: advanced

Description

Contains all non standard fields. Those fields are more rarely shown on an esl or are very specific.

Fields

Example of advanced

{
	"id": "210987654321",
	"domain": "corporationName.store",
	"name": "Bread",
	"price": 1.1,
	"unitPriceUnit": "1kg",
	"unitPrice": 2.2,
	"currency": "$",
	"capacity": "500g",
	"certificates": {
		"ecologic": true,
		"environmentallyFriendly": true
	},
	"localProduct": true,
	"packaging": {
		"height": 45,
		"width": 5
	},
	"taxes": {
		"vat": 0.21
	},
	"multimedia": {
		"picto": "bread-small.png",
		"image": "bread-high.png"
	}
}

Category: composition

Description

Contains allergens, composition, recommanded intake, ... Every informations relatives to the composition of an alimentary item.

Fields

Example of composition

{
	"id": "210987654321",
	"domain": "corporationName.store",
	"name": "Bread",
	"price": 1.1,
	"unitPriceUnit": "1kg",
	"unitPrice": 2.2,
	"currency": "$",
	"capacity": "500g",
	"composition": {
		"dietetic": true,
		"ingredients": "Whole wheat flour, Water, Wheat gluten, Salt",
		"allergens": {
			"barley": "YES",
			"gluten": "YES",
			"peanuts": "ALIBI"
		},
		"nutritionals": {
			"unit": "100g",
			"calories": {
				"recommandedIntakePercent": 1800,
				"value": 88
			},
			"salt": {
				"recommandedIntakePercent": 6,
				"value": 0.5
			},
			"sugars": {
				"recommandedIntakePercent": 37.5,
				"value": 2
			}
		}
	}
}