gs1 rest tradeiteminformation · sortby a trade item attribute name to sort response by....

36
GS1 REST TradeItemInformation – TradeItem.api Release 1.7, June 2020

Upload: others

Post on 24-Jul-2020

3 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation –

TradeItem.api

Release 1.7, June 2020

Page 2: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 2 of 36

Document Summary

Document Item Current Value

Document Name GS1 REST TradeItemInformation – TradeItem.api

Document Date June 2020

Document Version 1.7

Contributors

Name Organisation

Anna Edling GS1 Sweden

Log of Changes

Release Date of Change Changed By Summary of Change

.1 2019-07-02 Anna Edling Initialize document

1.0 2019-09-23 Anna Edling Updated with new parameters and examples

1.1 2019-10-04 Anna Edling Updated response information and models and corrected parameter data type

1.2 2019-11-05 Anna Edling Updated descriptions regarding product/GDSN flow, added required parameters for GetItemById, and added information about authentication

1.3 2019-12-09 Anna Edling Updated parameter names, descriptions regarding product/GDSN flow and request and response models and examples

1.4 2019-12-11 Anna Edling Updated the cin information for the get endpoints

1.5 2020-01-15 Anna Edling Updated information regarding examples and parameters

1.6 2020-02-14 Anna Edling Updated section 7.1 about CIN

1.7 2020-06-16 Anna Edling Corrected and updated examples

Disclaimer

GS1®, under its IP Policy, seeks to avoid uncertainty regarding intellectual property claims by requiring the participants in the Work Group

that developed this GS1 TradeItem.api Specification to agree to grant to GS1 members a royalty-free licence or a RAND licence to Necessary Claims, as that term is defined in the GS1 IP Policy. Furthermore, attention is drawn to the possibility that an implementation of one or more features of this Specification may be the subject of a patent or other intellectual property right that does not involve a Necessary Claim. Any such patent or other intellectual property right is not subject to the licencing obligations of GS1. Moreover, the agreement to grant licences provided under the GS1 IP Policy does not include IP rights and any claims of third parties who were not participants in the Work Group.

Accordingly, GS1 recommends that any organisation developing an implementation designed to be in conformance with this Specification should determine whether there are any patents that may encompass a specific implementation that the organisation is developing in compliance with the Specification and whether a licence under a patent or other intellectual property right is needed. Such a determination of a need for licencing should be made in view of the details of the specific system designed by the organisation in consultation with their own patent counsel.

THIS DOCUMENT IS PROVIDED “AS IS” WITH NO WARRANTIES WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR PARTICULAR PURPOSE, OR ANY WARRANTY OTHER WISE ARISING OUT OF THIS SPECIFICATION. GS1 disclaims all liability for any damages arising from use or misuse of this document, whether special, indirect, consequential, or compensatory damages, and including liability for infringement of any intellectual property rights, relating to use of information in or reliance upon this document.

Page 3: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 3 of 36

GS1 retains the right to make changes to this document at any time, without notice. GS1 makes no warranty for the use of this document and assumes no responsibility for any errors which may appear in the document, nor does it make a commitment to update the information contained herein. GS1 and the GS1 logo are registered trademarks of GS1 AISBL.

Table of Contents

1 Overview ...................................................................................................... 4

2 REST service ................................................................................................. 4

3 TradeItem.Api............................................................................................... 4

3.1 TradeItem Service (REST) ................................................................................................ 4

3.2 Authentication ................................................................................................................ 4

3.3 Endpoints ....................................................................................................................... 4

3.3.1 Product flow ........................................................................................................... 4

3.3.2 GDSN flow ............................................................................................................. 5

4 Product flow ................................................................................................. 6

4.1 Product flow - Endpoint: Search ........................................................................................ 6

4.1.1 Product flow – Endpoint: Search example .................................................................. 9

4.2 Product flow - Endpoint: GetItemById ............................................................................. 11

4.2.1 Product flow - Endpoint: GetItemById example ........................................................ 14

4.3 Product flow - Endpoint: GetItemByIdentification .............................................................. 15

4.3.1 Product flow - Endpoint: GetItemByIdentification example ......................................... 18

5 GDSN flow .................................................................................................. 20

5.1 GDSN flow - Endpoint: Search ........................................................................................ 20

5.1.1 GDSN flow – Endpoint: Search example................................................................... 23

5.2 GDSN flow - Endpoint: GetItemById ................................................................................ 25

5.2.1 GDSN flow - Endpoint: GetItemById example ........................................................... 28

5.3 GDSN flow - Endpoint: GetItemByIdentification ................................................................ 29

5.3.1 GDSN flow - Endpoint: GetItemByIdentification example ........................................... 32

6 Enumeration types ...................................................................................... 34

6.1 dataType ...................................................................................................................... 34

6.2 itemStatus ................................................................................................................... 35

6.3 itemTypes .................................................................................................................... 35

6.4 latestQaResult .............................................................................................................. 35

7 Parameters dictionary ................................................................................ 35

7.1 Catalogue Item Notification (CIN) – how to retrieve details like allergens and nutritional contents 36

8 API Limitations ........................................................................................... 36

Page 4: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 4 of 36

1 Overview

This document contains REST descriptions to search and get trade item information. Two different data type flows exist: product or GDSN. These are specified in separate sections in this documentation.

Search to get basic info about items and their internal id. The id can then be used to retrieve more specific data through the getbyid-endpoint.

2 REST service

Name Description

TradeItem.api A new REST service is implemented for Validoo Platform. Provides functionality to search and get trade item information for either product or GDSN flow.

3 TradeItem.Api

3.1 TradeItem Service (REST)

Root endpoints

Environment Url

Pre-Prod https://services-preprod.validoo.se/tradeitem.api Prod https://services.validoo.se/tradeitem.api

3.2 Authentication

Authentication is handled via tokens. The client requests a token with username and password. Note that the credentials will be obtained via GS1. To be eligible to receive credentials you must be a GS1 customer. The credentials are api specific, they do not work for front-end.

More detailed information about authentication is included in ‘GS1_REST_Authentication.pdf’ which will be sent separately after api user activation.

3.3 Endpoints

There are three endpoints, but they serve different flows based on parameter dataType.

3.3.1 Product flow

The product flow returns the current version of the item. To retrieve data in this flow user should have a Receiver or Buyer service at GS1.

Page 5: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 5 of 36

Name Description

Search Search for product data for trade items

GetItemById Get product data for a trade item for the given id GetItemByIdentification Get product data for a trade item based on identification (GTIN, GLN, Target

market, Data recipient)

3.3.2 GDSN flow

The GDSN flow returns current and future items. To retrieve data in this flow the user should have a Buyer service at GS1.

Name Description

Search Search for GDSN data for trade items

GetItemById Get GDSN data for a trade item for the given id GetItemByIdentification Get GDSN data for a trade item based on identification (GTIN, GLN, Target

market, Data recipient, Version)

Page 6: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 6 of 36

4 Product flow

To get product data, use parameter dataType = “Product”.

4.1 Product flow - Endpoint: Search

Search trade items. To get product data, use dataType = “Product”. Note: If dataType is not set, product data will still be returned as this is the default dataType.

• Depending on input parameters Search can return many items. These will be iteratively returned.

• If limit is not set, there is a default limit set.

• Parameters latestQaResult, itemTypes and dataType are enumerations listed in this documentation.

• Response attributes containing QaResult will only be included if the user has a Q-lab Buyer Service.

Parameters Search without parameter dataType specified or dataType = “Product”, i.e. product data is returned. Please note, this is an example to display all available parameters. To perform an actual search only a few parameters need to be used. See example in section 4.1.1. Name Description

request Search parameters (body)

Example Value | Model

/tradeitem.api/TradeItemInformation/searchPOST

Page 7: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 7 of 36

Responses Response for request with dataType not specified or dataType = “Product”, i.e. product data is returned. Code Description

200 Example Value | Model

{

"latestQaResult": "string",

"gtins": [

"05707653002411"

],

"informationProviderGln": [

"7300009005903"

],

"informationProviderName": "string",

"brandOwnerGln": "string",

"brandOwnerName": "string",

"brandName": "string",

"functionalName": "string",

"gpcCategoryCode": [

"string"

],

"targetMarketCountryCode": "string",

"lastChangeDateTimeFrom": "2019-08-22T10:28:46.622Z",

"lastChangeDateTimeTo": "2019-09-22T10:28:46.622Z",

"limit": 0,

"skip": 0,

"sortBy": "string",

"sortAscending": true,

"itemTypes": [

"Base"

],

"dataRecipient": [

"00000040413199"

],

"dataType": "Product"

}

Success

Page 8: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 8 of 36

401

403

500

Example Value | Model

{

"results": [

{

"gtin": "05707653002411",

"informationProviderGln": "7300009005903",

"informationProviderName": "string",

"targetMarketCountryCode": "string",

"targetMarketName": "string",

"brandOwnerGln": "7300009005903",

"brandOwnerName": "string",

"descriptiveSize": "string",

"brandName": "string",

"gpcCode": "string",

"isTradeItemABaseUnit": true,

"isTradeItemAConsumerUnit": true,

"isTradeItemAnOrderableUnit": false, "isTradeItemADisplayUnit": true,

"creationDateTime": "2019-08-24T13:25:29.017Z",

"effectiveDateTime": "2019-09-05T13:25:29.017Z", "startAvailabilityDate": "2019-09-08T13:25:29.017Z",

"consumerFirstAvailabilityDateTime": "2019-07-05T13:25:29.017Z",

"lastChangeDateTime": "2019-09-10T13:25:29.017Z",

"firstShipDateTime": "2019-08-01T13:25:29.017Z",

"functionalName": "string",

"lastQaResultTii": "string",

"sampleTypeTii": "string",

"qaDateTimeTii": "2019-07-05T13:25:29.017Z",

"lastQaResultFbe": "string",

"sampleTypeFbe": "string",

"qaDateTimeFbe": "2019-07-05T13:25:29.017Z",

"itemId": 0,

"status": "Published", "topItem": true }

]

}

Unauthorized

Forbidden

Server error

Page 9: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 9 of 36

4.1.1 Product flow – Endpoint: Search example

Parameters Search with dataType = “Product”, i.e. product data is returned. This is a search for items that have been changed between a specified datetime span for a specific InformationProviderGLN where the user is set as dataRecipient. LatestQaResult must also be OK. The response will be sorted ascending by brandname. Name Example

request Search parameters (body)

Example Value | Model

{

"traceId": "string",

"errors": [

{

"code": "string",

"message": "string",

"params": {

"additionalProp1": "string",

"additionalProp2": "string",

"additionalProp3": "string"

},

"exception": {

"message": "string",

"stackTrace": "string",

"data": [

{

"key": "string",

"value": "string"

}

]

}

}

]

}

Page 10: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 10 of 36

Response Response for request above with dataType = “Product”, i.e. product data is returned. Please note that there is only one item returned in this example, search can deliver several. Code Description

200 Example Value | Model

{

"latestQaResult": "Ok", //use only if you have a Q-lab Buyer Service

"informationProviderGln": [

"7300009005903"

],

"targetMarketCountryCode": "752",

"lastChangeDateTimeFrom": "2019-08-22T10:28:46.622Z",

"lastChangeDateTimeTo": "2019-09-22T10:28:46.622Z",

"sortBy": "brandName",

"sortAscending": true,

"dataRecipient": [ //use only if you know you are set as dataRecipient

"7320240010014"

],

"dataType": "Product"

}

Success

Page 11: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 11 of 36

4.2 Product flow - Endpoint: GetItemById

Gets item by Id if it exists. To get product data, use dataType = “Product”. Note: If dataType is not set, product data will still be returned as this is the default dataType.

• Parameter dataRecipient can be used to get items addressed to you. If set, only addressed items will be returned.

• Response attributes containing QaResult will only be included if the user has a Q-lab Buyer Service.

Important: The response attribute “cin” is the Catalogue Item Notification of the requested trade item as a base64 string. Decoded it will be in the specified format set in the request (Xml/Text). If the item searched for has any children, they are included in the “cin”.

/tradeitem.api/TradeItemInformation/getItemByIdGET

{

"results": [

{

"gtin": "05707653002411",

"informationProviderGln": "7300009005903",

"informationProviderName": "The Whole Company",

"targetMarketCountryCode": "752",

"targetMarketName": "Sweden",

"brandOwnerGln": "7300009005903",

"brandOwnerName": "The Whole Company", "descriptiveSize": "7 st",

"brandName": "The Whole Brand", "gpcCode": "10000206",

"isTradeItemABaseUnit": true,

"isTradeItemAConsumerUnit": true,

"isTradeItemAnOrderableUnit": false, "isTradeItemADisplayUnit": true,

"creationDateTime": "2019-08-24T13:25:29.017Z",

"effectiveDateTime": "2019-09-05T13:25:29.017Z", "startAvailabilityDate": "2019-09-08T13:25:29.017Z",

"consumerFirstAvailabilityDateTime": "2019-07-05T13:25:29.017Z",

"lastChangeDateTime": "2019-08-23T13:25:29.017Z",

"firstShipDateTime": "2019-08-01T13:25:29.017Z",

"functionalName": "Whole Choice",

"lastQaResultTii": "Ok",

"sampleTypeTii": "Production",

"qaDateTimeTii": "2019-07-05T13:25:29.017Z",

"lastQaResultFbe": "Ok",

"sampleTypeFbe": "Production",

"qaDateTimeFbe": "2019-07-05T13:25:29.017Z",

"itemId": 1234,

"status": "Published", "topItem": true }

]

}

Page 12: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 12 of 36

Parameters Name Description

id * Item idinteger

($int32)

cinFormat CIN format, “Xml” or “Text”string Default value: “Xml” (query)

dataRecipient Recipient of the itemstring

(query)

dataType Data type, “Product” or “Gdsn” string Default value: “Product” (query)

Responses Response without parameter dataType specified or dataType = “Product”, i.e. product data is returned. Code Description

200

Example Value | Model

Success

Page 13: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 13 of 36

401

403

500

Example Value | Model

{

"results": [

{

"cin": "string",

"gtin": "00000040413198",

"informationProviderGln": "7320240030135",

"informationProviderName": "string",

"targetMarketCountryCode": "string",

"targetMarketName": "string",

"brandOwnerGln": "7320240030135",

"brandOwnerName": "string",

"descriptiveSize": "string",

"brandName": "string",

"gpcCode": "string",

"isTradeItemABaseUnit": true,

"isTradeItemAConsumerUnit": true,

"isTradeItemAnOrderableUnit": true, "isTradeItemADisplayUnit": true,

"creationDateTime": "2019-07-05T13:25:29.017Z",

"effectiveDateTime": "2019-07-05T13:25:29.017Z", "startAvailabilityDate": "2019-07-05T13:25:29.017Z",

"consumerFirstAvailabilityDateTime": "2019-07-05T13:25:29.017Z",

"lastChangeDateTime": "2019-07-05T13:25:29.017Z",

"firstShipDateTime": "2019-07-05T13:25:29.017Z",

"functionalName": "string",

"lastQaResultTii": "string",

"sampleTypeTii": "string",

"qaDateTimeTii": "2019-07-05T13:25:29.017Z",

"lastQaResultFbe": "string",

"sampleTypeFbe": "string",

"qaDateTimeFbe": "2019-07-05T13:25:29.017Z",

"status": "string",

"itemId": 0

}

]

}

Unauthorized

Forbidden

Server error

Page 14: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 14 of 36

4.2.1 Product flow - Endpoint: GetItemById example

Parameters Search with dataType = “Product”, i.e. product data is returned. This is a search for an item by id and the response cinFormat will be in XML. Name Example

id 12345integer

($int32)

cinFormat Xmlstring

(query)

dataRecipient -string

(query)

dataType Product string

(query)

Response

{

"traceId": "string",

"errors": [

{

"code": "string",

"message": "string",

"params": {

"additionalProp1": "string",

"additionalProp2": "string",

"additionalProp3": "string"

},

"exception": {

"message": "string",

"stackTrace": "string",

"data": [

{

"key": "string",

"value": "string"

}

]

}

}

]

}

/tradeitem.api/TradeItemInformation/getItemById?id=12345&format=Xml&dataType=ProductGET

Page 15: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 15 of 36

Response for request above with dataType = “Product”, i.e. product data is returned. The cin has been shortened. Code Description

200

Example Value | Model

4.3 Product flow - Endpoint: GetItemByIdentification

Gets item by identifying parameters. To get product data, use dataType = “Product”. Note: If dataType is not set, product data will still be returned as this is the default dataType.

/tradeitem.api/TradeItemInformation/getItemByIdentificationGET

Success

{

"results": [

{

"cin": "

PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz48Y2F0YW",

"gtin": "00000040413198",

"informationProviderGln": "7320240030135",

"informationProviderName": "The Whole Company",

"targetMarketCountryCode": "752",

"targetMarketName": "Sweden",

"brandOwnerGln": "7320240030135",

"brandOwnerName": "The Whole Company",

"descriptiveSize": "7 st",

"brandName": "The Whole Brand",

"gpcCode": "10000206",

"isTradeItemABaseUnit": true,

"isTradeItemAConsumerUnit": true,

"isTradeItemAnOrderableUnit": true, "isTradeItemADisplayUnit": true,

"creationDateTime": "2019-07-05T13:25:29.017Z",

"effectiveDateTime": "2019-07-05T13:25:29.017Z", "startAvailabilityDate": "2019-07-05T13:25:29.017Z",

"consumerFirstAvailabilityDateTime": "2019-07-05T13:25:29.017Z",

"lastChangeDateTime": "2019-07-05T13:25:29.017Z",

"firstShipDateTime": "2019-07-05T13:25:29.017Z",

"functionalName": "Whole Choice",

"lastQaResultTii": "Ok",

"sampleTypeTii": "Production",

"qaDateTimeTii": "2019-07-05T13:25:29.017Z",

"lastQaResultFbe": "Ok",

"sampleTypeFbe": "Production",

"qaDateTimeFbe": "2019-07-05T13:25:29.017Z",

"status": "Published",

"itemId": 12345

}

]

}

Page 16: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 16 of 36

• Parameter dataRecipient can be used to get items addressed to you. If set, only addressed items will be returned.

• Response attributes containing QaResult will only be included if the user has a Q-lab Buyer Service.

Important: The response attribute “cin” is the Catalogue Item Notification of the requested trade item as a base64 string. Decoded it will be in the specified format set in the request (Xml/Text). If the item searched for has any children, they are included in the “cin”.

Parameters Name Description

gtin * string

(query)

informationProviderGln * string

(query)

targetMarket * string

(query)

cinFormat CIN format, “Xml” or “Text” string Default value: “Xml” (query)

dataRecipient Recipient of the itemstring

(query)

dataType Data type, “Product” or “Gdsn” string Default value: “Product” (query)

Responses Response without parameter dataType specified or dataType = “Product”, i.e. product data is returned. Code Description

200

Success

Page 17: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 17 of 36

Example Value | Model

401

403

500

Example Value | Model

{

"results": [

{

"cin": "string",

"gtin": "00000040413198",

"informationProviderGln": "7320240030135",

"informationProviderName": "string",

"targetMarketCountryCode": "string",

"targetMarketName": "string",

"brandOwnerGln": "7320240030135",

"brandOwnerName": "string",

"descriptiveSize": "string",

"brandName": "string",

"gpcCode": "string",

"isTradeItemABaseUnit": true,

"isTradeItemAConsumerUnit": true,

"isTradeItemAnOrderableUnit": true, "isTradeItemADisplayUnit": true,

"creationDateTime": "2019-07-05T13:25:29.017Z",

"effectiveDateTime": "2019-07-05T13:25:29.017Z", "startAvailabilityDate": "2019-07-05T13:25:29.017Z",

"consumerFirstAvailabilityDateTime": "2019-07-05T13:25:29.017Z",

"lastChangeDateTime": "2019-07-05T13:25:29.017Z",

"firstShipDateTime": "2019-07-05T13:25:29.017Z",

"functionalName": "string",

"lastQaResultTii": "string",

"sampleTypeTii": "string",

"qaDateTimeTii": "2019-07-05T13:25:29.017Z",

"lastQaResultFbe": "string",

"sampleTypeFbe": "string",

"qaDateTimeFbe": "2019-07-05T13:25:29.017Z",

"status": "string", "itemId": 0

}

]

}

Unauthorized

Forbidden

Server error

Page 18: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 18 of 36

4.3.1 Product flow - Endpoint: GetItemByIdentification example

Parameters Search with dataType = “Product”, i.e. product data is returned. This is a search for a specific GTIN, InformationProviderGln for a specified targetMarket and dataRecipient. The response cinFormat will be in XML. Name Example

gtin * 00000040413198string

(query)

informationProviderGln * 7320240030135 string

(query)

targetMarket * 752string

(query)

{

"traceId": "string",

"errors": [

{

"code": "string",

"message": "string",

"params": {

"additionalProp1": "string",

"additionalProp2": "string",

"additionalProp3": "string"

},

"exception": {

"message": "string",

"stackTrace": "string",

"data": [

{

"key": "string",

"value": "string"

}

]

}

}

]

}

/tradeitem.api/TradeItemInformation/getItemByIdentification?gtin=7320240030135&infor

mationProvider=00000040413198&targetMarket=752&cinFormat=Xml&dataRecipient=732024001

0014&dataType=Product

GET

Page 19: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 19 of 36

cinFormat Xml string

(query)

dataRecipient 7320240010014string

(query)

dataType Product string

(query)

Response Response for request above with dataType = “Product”, i.e. product data is returned. Code Description

200

Example Value | Model

Success

{

"results": [

{

"cin": "string",

"gtin": "00000040413198",

"informationProviderGln": "7320240030135",

"informationProviderName": "string",

"targetMarketCountryCode": "string",

"targetMarketName": "string",

"brandOwnerGln": "7320240030135",

"brandOwnerName": "string",

"descriptiveSize": "string",

"brandName": "string",

"gpcCode": "string",

"isTradeItemABaseUnit": true,

"isTradeItemAConsumerUnit": true,

"isTradeItemAnOrderableUnit": true, "isTradeItemADisplayUnit": true,

"creationDateTime": "2019-07-05T13:25:29.017Z",

"effectiveDateTime": "2019-07-05T13:25:29.017Z", "startAvailabilityDate": "2019-07-05T13:25:29.017Z",

"consumerFirstAvailabilityDateTime": "2019-07-05T13:25:29.017Z",

"lastChangeDateTime": "2019-07-05T13:25:29.017Z",

"firstShipDateTime": "2019-07-05T13:25:29.017Z",

"functionalName": "string",

"lastQaResultTii": "string",

"sampleTypeTii": "string",

"qaDateTimeTii": "2019-07-05T13:25:29.017Z",

"lastQaResultFbe": "string",

"sampleTypeFbe": "string",

"qaDateTimeFbe": "2019-07-05T13:25:29.017Z",

"status": "Published",

"itemId": 12345

}

]

}

Page 20: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 20 of 36

5 GDSN flow

To get data for the GDSN flow, use parameter dataType = “Gdsn”.

5.1 GDSN flow - Endpoint: Search

Search trade items. To get GDSN data, use dataType = “Gdsn”. Note: If dataType is not set, product data will be returned as this is the default dataType.

• Depending on input parameters Search can return many items. These will be iteratively returned.

• If limit is not set, there is a default limit set.

• Parameters latestQaResult, itemTypes and dataType are enumerations listed in this documentation.

• Response attributes containing QaResult will only be included if the user has a Q-lab Buyer Service.

Parameters Search with parameter dataType = “Gdsn”, i.e. GDSN data is returned. Please note, this is a search example to display all available parameters. To perform an actual search only a few parameters need to be used. See example in in section 5.1.1. Name Description

request Search parameters (body)

Example Value | Model

/tradeitem.api/TradeItemInformation/searchPOST

Page 21: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 21 of 36

Responses Response for request with parameter dataType = “Gdsn”, i.e. GDSN data is returned. Code Description

200

Example Value | Model

{

"onlyTopItems": true,

"latestQaResult": "string",

"gtins": [

"00000040413198"

],

"informationProviderGln": [

"7320240030135"

],

"informationProviderName": "string",

"brandOwnerGln": "7320240030135",

"brandOwnerName": "string",

"brandName": "string",

"functionalName": "string",

"gpcCategoryCode": [

"string"

],

"targetMarketCountryCode": "string",

"lastChangeDateTimeFrom": "2019-07-05T13:28:46.622Z",

"lastChangeDateTimeTo": "2019-07-05T13:28:46.622Z",

"limit": 0,

"skip": 0,

"sortBy": "string",

"sortAscending": true,

"itemStatus": [

"published"

],

"itemTypes": [

"Base"

],

"onlyCurrentVersion": true,

"dataRecipient": [

"00000040413198"

],

"dataType": "Gdsn"

}

Success

Page 22: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 22 of 36

401

403

500

Example Value | Model

{

"results": [

{

"gtin": "00000040413198",

"informationProviderGln": "7320240030135",

"informationProviderName": "string",

"targetMarketCountryCode": "string",

"targetMarketName": "string",

"brandOwnerGln": "7320240030135",

"brandOwnerName": "string",

"descriptiveSize": "string",

"brandName": "string",

"gpcCode": "string",

"isTradeItemABaseUnit": true,

"isTradeItemAConsumerUnit": true,

"isTradeItemAnOrderableUnit": true,

"isTradeItemADisplayUnit": true,

"creationDateTime": "2019-07-05T13:25:29.017Z",

"effectiveDateTime": "2019-07-05T13:25:29.017Z",

"startAvailabilityDate": "2019-07-05T13:25:29.017Z",

"consumerFirstAvailabilityDateTime": "2019-07-05T13:25:29.017Z",

"lastChangeDateTime": "2019-07-05T13:25:29.017Z",

"firstShipDateTime": "2019-07-05T13:25:29.017Z",

"functionalName": "string",

"lastQaResultTii": "string",

"sampleTypeTii": "string",

"qaDateTimeTii": "2019-07-05T13:25:29.017Z",

"lastQaResultFbe": "string",

"sampleTypeFbe": "string", "qaDateTimeFbe": "2019-07-05T13:25:29.017Z",

"itemId": 0,

"status": "string",

"topItem": true

}

]

}

Unauthorized

Forbidden

Server error

Page 23: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 23 of 36

5.1.1 GDSN flow – Endpoint: Search example

Parameters Search with parameter dataType = “Gdsn”, i.e. GDSN data is returned. This is a search for top items with OK latestQaResult for a specific InformationProviderGLN. Only current version will be returned. Name Example

request Search parameters (body)

Example Value | Model

{

"traceId": "string",

"errors": [

{

"code": "string",

"message": "string",

"params": {

"additionalProp1": "string",

"additionalProp2": "string",

"additionalProp3": "string"

},

"exception": {

"message": "string",

"stackTrace": "string",

"data": [

{

"key": "string",

"value": "string"

}

]

}

}

]

}

Page 24: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 24 of 36

Response Response for above request with parameter dataType = “Gdsn”, i.e. GDSN data is returned. Code Description

200

Example Value | Model

{

"onlyTopItems": true,

"latestQaResult": "Ok", //use only if you have a Q-lab Buyer Service "informationProviderGln": [

"7320240030135"

],

"onlyCurrentVersion": true,

"dataType": "Gdsn"

}

Success

Page 25: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 25 of 36

5.2 GDSN flow - Endpoint: GetItemById

Gets item by Id if it exists. To get GDSN data, use dataType = “Gdsn”. Note: If dataType is not set, product data will be returned as this is the default dataType.

• Parameter dataRecipient can be used to get items addressed to you. If set, only addressed items will be returned.

• Response attributes containing QaResult will only be included if the user has a Q-lab Buyer Service.

Important: The response attribute “cin” is the Catalogue Item Notification of the requested trade item as a base64 string. Decoded it will be in the specified format set in the request (Xml/Text). If the item searched for has any children, they are included in the “cin”.

/tradeitem.api/TradeItemInformation/getItemByIdGET

{

"results": [

{

"gtin": "00000040413198",

"informationProviderGln": "7320240030135",

"informationProviderName": "The Whole Company",

"targetMarketCountryCode": "752",

"targetMarketName": "Sweden",

"brandOwnerGln": "7320240030135",

"brandOwnerName": "The Whole Company",

"descriptiveSize": "7 st",

"brandName": "The Whole Brand",

"gpcCode": "10000206",

"isTradeItemABaseUnit": true,

"isTradeItemAConsumerUnit": true,

"isTradeItemAnOrderableUnit": true,

"isTradeItemADisplayUnit": true,

"creationDateTime": "2019-07-05T13:25:29.017Z",

"effectiveDateTime": "2019-07-05T13:25:29.017Z",

"startAvailabilityDate": "2019-07-05T13:25:29.017Z",

"consumerFirstAvailabilityDateTime": "2019-07-05T13:25:29.017Z",

"lastChangeDateTime": "2019-07-05T13:25:29.017Z",

"firstShipDateTime": "2019-07-05T13:25:29.017Z",

"functionalName": "Whole Organic",

"lastQaResultTii": "Ok",

"sampleTypeTii": "Production",

"qaDateTimeTii": "2019-07-05T13:25:29.017Z",

"lastQaResultFbe": "Ok",

“sampleTypeFbe”: “Production”,

"qaDateTimeFbe": "2019-07-05T13:25:29.017Z",

"itemId": 12345,

"status": "Published",

"topItem": true

}

]

}

Page 26: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 26 of 36

Parameters Name Description

id * Item idinteger

($int32)

cinFormat CIN format, “Xml” or “Text” string Default value: “Xml” (query)

dataRecipient Recipient of the itemstring

(query)

dataType Data type, “Product” or “Gdsn” string Default value: “Product” (query)

Responses Response for request with dataType = “Gdsn”, i.e. GDSN data is returned. Code Description

200

Example Value | Model

Success

Page 27: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 27 of 36

401

403

500

Unauthorized

Forbidden

Server error

{

"results": [

{

"cin": "string",

"gtin": "00000040413198",

"informationProviderGln": "string",

"informationProviderName": "string",

"targetMarketCountryCode": "string",

"targetMarketName": "string",

"brandOwnerGln": "string",

"brandOwnerName": "string",

"descriptiveSize": "string",

"brandName": "string",

"gpcCode": "string",

"isTradeItemABaseUnit": true,

"isTradeItemAConsumerUnit": true,

"isTradeItemAnOrderableUnit": true,

"isTradeItemADisplayUnit": true,

"creationDateTime": "2019-09-02T12:15:11.789Z",

"effectiveDateTime": "2019-09-02T12:15:11.789Z",

"startAvailabilityDate": "2019-09-02T12:15:11.789Z",

"consumerFirstAvailabilityDateTime": "2019-09-02T12:15:11.789Z",

"lastChangeDateTime": "2019-09-02T12:15:11.789Z",

"firstShipDateTime": "2019-09-02T12:15:11.789Z",

"functionalName": "string",

"lastQaResultTii": "string",

"sampleTypeTii": "string",

"qaDateTimeTii": "2019-09-02T12:15:11.789Z",

"lastQaResultFbe": "string",

"sampleTypeFbe": "string",

"qaDateTimeFbe": "2019-09-02T12:15:11.789Z",

"status": "string",

"itemId": 0

}

]

}

Page 28: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 28 of 36

Example Value | Model

5.2.1 GDSN flow - Endpoint: GetItemById example

Parameters Search with dataType = “Gdsn”, i.e. GDSN data is returned. This is a search for an item by id where the specified GLN is set as dataRecipient. The response cinFormat will be in XML. Name Example

id * 12345integer

($int32)

cinFormat Xmlstring

(query)

dataRecipient 7320240010014string

(query)

dataType Gdsn string

(query)

{

"traceId": "string",

"errors": [

{

"code": "string",

"message": "string",

"params": {

"additionalProp1": "string",

"additionalProp2": "string",

"additionalProp3": "string"

},

"exception": {

"message": "string",

"stackTrace": "string",

"data": [

{

"key": "string",

"value": "string"

}

]

}

}

]

}

/tradeitem.api/TradeItemInformation/getItemById?id=12345&format=Xml&dataType=GdsnGET

Page 29: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 29 of 36

Response Response for above request with dataType = “Gdsn”, i.e. GDSN data is returned. The cin has been shortened. Code Description

200

Example Value | Model

5.3 GDSN flow - Endpoint: GetItemByIdentification

/tradeitem.api/TradeItemInformation/getItemByIdentificationGET

Success

{

"results": [

{

"cin":

"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz48Y2F0YW",

"gtin": "00000040413198",

"informationProviderGln": "7320240030135",

"informationProviderName": "The Whole Company",

"targetMarketCountryCode": "752",

"targetMarketName": "Sweden",

"brandOwnerGln": "7320240030135",

"brandOwnerName": "The Whole Company",

"descriptiveSize": "7 st",

"brandName": "The Whole Brand",

"gpcCode": "10000206",

"isTradeItemABaseUnit": true,

"isTradeItemAConsumerUnit": true,

"isTradeItemAnOrderableUnit": true,

"isTradeItemADisplayUnit": true,

"creationDateTime": "2019-09-02T12:15:11.789Z",

"effectiveDateTime": "2019-09-02T12:15:11.789Z",

"startAvailabilityDate": "2019-09-02T12:15:11.789Z",

"consumerFirstAvailabilityDateTime": "2019-09-02T12:15:11.789Z",

"lastChangeDateTime": "2019-09-02T12:15:11.789Z",

"firstShipDateTime": "2019-09-02T12:15:11.789Z",

"functionalName": "Whole Organic",

"lastQaResultTii": "Ok",

"sampleTypeTii": "Production",

"qaDateTimeTii": "2019-09-02T12:15:11.789Z",

"lastQaResultFbe": "Ok",

"sampleTypeFbe": "Production",

"qaDateTimeFbe": "2019-09-02T12:15:11.789Z",

"status": "Published",

"itemId": 12345

}

]

}

Page 30: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 30 of 36

Gets item by identifying parameters. To get GDSN data, use dataType = “Gdsn”. Note: If dataType is not set, product data will be returned as this is the default dataType.

• Parameter dataRecipient can be used to get items addressed to you. If set, only addressed items will be returned.

• Response attributes containing QaResult will only be included if the user has a Q-lab Buyer Service.

Important: The response attribute “cin” is the Catalogue Item Notification of the requested trade item as a base64 string. Decoded it will be in the specified format set in the request (Xml/Text). If the item searched for has any children, they are included in the “cin”.

Parameters Name Description

gtin * string

(query)

informationProviderGln * string

(query)

targetMarket * string

(query)

cinFormat CIN format, “Xml” or “Text” string Default value: “Xml” (query)

dataRecipient Recipient of the itemstring

(query)

onlyCurrentVersion If true, returns only current version, not future if it exists boolean Default value: false (query)

includeDiscontinued If true, discontinued items will be returned boolean Default value: false (query)

dataType Data type, “Product” or “Gdsn” string Default value: “Product” (query)

Responses Response for request with dataType = “Gdsn”, i.e. GDSN data is returned. Code Description

200

Success

Page 31: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 31 of 36

Example Value | Model 401

403

500

Example Value | Model

Unauthorized

Forbidden

Server error

{

"results": [

{

"cin": "string",

"gtin": "00000040413198",

"informationProviderGln": "string",

"informationProviderName": "string",

"targetMarketCountryCode": "string",

"targetMarketName": "string",

"brandOwnerGln": "string",

"brandOwnerName": "string",

"descriptiveSize": "string",

"brandName": "string",

"gpcCode": "string",

"isTradeItemABaseUnit": true,

"isTradeItemAConsumerUnit": true,

"isTradeItemAnOrderableUnit": true,

"isTradeItemADisplayUnit": true,

"creationDateTime": "2019-09-02T12:15:11.789Z",

"effectiveDateTime": "2019-09-02T12:15:11.789Z",

"startAvailabilityDate": "2019-09-02T12:15:11.789Z",

"consumerFirstAvailabilityDateTime": "2019-09-02T12:15:11.789Z",

"lastChangeDateTime": "2019-09-02T12:15:11.789Z",

"firstShipDateTime": "2019-09-02T12:15:11.789Z",

"functionalName": "string",

"lastQaResultTii": "string",

"sampleTypeTii": "string",

"qaDateTimeTii": "2019-09-02T12:15:11.789Z",

"lastQaResultFbe": "string",

"sampleTypeFbe": "string",

"qaDateTimeFbe": "2019-09-02T12:15:11.789Z",

"status": "string",

"itemId": 0

}

]

}

Page 32: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 32 of 36

5.3.1 GDSN flow - Endpoint: GetItemByIdentification example

Parameters Search with dataType = “Gdsn”, i.e. GDSN data is returned. This is a search for a specific GTIN and InformationProviderGln for a specified targetMarket. The response cinFormat will be in XML and if they exist current and future versions will be returned. No discontinued items will be returned. Name Example

gtin * 00000040413198string

(query)

informationProviderGln * 7320240030135string

(query)

targetMarket * 752string

(query)

cinFormat Xml string

(query)

{

"traceId": "string",

"errors": [

{

"code": "string",

"message": "string",

"params": {

"additionalProp1": "string",

"additionalProp2": "string",

"additionalProp3": "string"

},

"exception": {

"message": "string",

"stackTrace": "string",

"data": [

{

"key": "string",

"value": "string"

}

]

}

}

]

}

/tradeitem.api/TradeItemInformation/getItemByIdentification?gtin=7320240030135&infor

mationProvider=00000040413198&targetMarket=752&cinFormat=Xml&dataType=Gdsn GET

Page 33: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 33 of 36

dataRecipient -string

(query)

onlyCurrentVersion - boolean Default value: false (query)

includeDiscontinued - boolean Default value: false (query)

dataType Gdsn string

(query)

Response Response for above request with dataType = “Gdsn”, i.e. GDSN data is returned. The cin has been shortened. Code Description

200

Example Value | Model

Success

Page 34: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 34 of 36

6 Enumeration types

6.1 dataType

Value Description

Product Product data will be returned

Gdsn GDSN data will be returned

{

"results": [

{

"cin":

"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz48Y2F0YW",

"gtin": "00000040413198",

"informationProviderGln": "7320240030135",

"informationProviderName": "The Whole Company",

"targetMarketCountryCode": "752",

"targetMarketName": "Sweden",

"brandOwnerGln": "7320240030135",

"brandOwnerName": "The Whole Company",

"descriptiveSize": "7 st",

"brandName": "The Whole Brand",

"gpcCode": "10000206",

"isTradeItemABaseUnit": true,

"isTradeItemAConsumerUnit": true,

"isTradeItemAnOrderableUnit": true,

"isTradeItemADisplayUnit": true,

"creationDateTime": "2019-09-02T12:15:11.789Z",

"effectiveDateTime": "2019-09-02T12:15:11.789Z",

"startAvailabilityDate": "2019-09-02T12:15:11.789Z",

"consumerFirstAvailabilityDateTime": "2019-09-02T12:15:11.789Z",

"lastChangeDateTime": "2019-09-02T12:15:11.789Z",

"firstShipDateTime": "2019-09-02T12:15:11.789Z",

"functionalName": "Whole Organic",

"lastQaResultTii": "Ok",

"sampleTypeTii": "Production",

"qaDateTimeTii": "2019-09-02T12:15:11.789Z",

"lastQaResultFbe": "Ok",

"sampleTypeFbe": "Production",

"qaDateTimeFbe": "2019-09-02T12:15:11.789Z",

"status": "Published",

"itemId": 12345

}

]

}

Page 35: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 35 of 36

6.2 itemStatus

Value Description

Published Item is published

Discontinued Item is discontinued

6.3 itemTypes

Value Description

Base Base unit. A trade item at base unit level contains no other items identified with a GTIN.

Consumer Consumer unit. The trade item is intended to be sold to a consumer or end user at point of sale

Orderable Orderable unit. The trade item is ordered from the supplier by a wholesaler, store, or similar.

Display Display unit

6.4 latestQaResult

Value Description

OK Both AssetCategories need to be OK for item to be returned

NOK At least one AssetCategory must be NOK for item to be returned

7 Parameters dictionary

Parameter Description

brandOwnerGln Identity of the brand owner according to GS1's identification system.

brandOwnerName Name of the party who owns the brand of the trade item.

cin Catalogue item notification message in the chosen format. See description below.

consumerFirstAvailabilityDate The first date and point of time at which a trade item is allowed to be sold to consumers.

Page 36: GS1 REST TradeItemInformation · sortBy A trade item attribute name to sort response by. startAvailabilityDate Date and point of time from when the item is available. 7.1 Catalogue

GS1 REST TradeItemInformation

Release 1.7, June 2020 © 2019 GS1 Sweden Page 36 of 36

Parameter Description

dataRecipient Identity, according to GS1's identification system.

effectiveDateTime Date and point of time from which the information in this business document is effective.

firstShipDate The earliest date and point of time that the trade item can be shipped according to the delivery terms, independent of any specific ship-from location.

functionalName The name of this trade item.

gpcCategoryCode Code indicating the classification category (brick code) for the trade item according to GPC.

informationProviderGln Identity, according to GS1's identification system, of the party who has created the business document.

informationProviderName Name of the party who has created the business document.

sortBy A trade item attribute name to sort response by.

startAvailabilityDate Date and point of time from when the item is available.

7.1 Catalogue Item Notification (CIN) – how to retrieve details like allergens and nutritional contents

A CIN is a carrier message that carries information about one trade item hierarchy. It also contains information about the content owners at the different levels (Message, Transaction and Document command), plus the Information provider and Data recipient and other relevant data about the trade item.

The json response from the two GET endpoints includes some trade item attributes but the details lie encoded in the attribute called “cin”. This attribute is a base64 string and decoded it contains all the trade item information in the requested format. XML is default but text can be requested. If the item searched for has any children, they are included in the “cin”.

8 API Limitations

There is no specific limit to the number of API calls per day, however GS1 reserves the right to implement limits at any time and from time to time without prior notice, and to restrict calls in our sole discretion. Please bundle your calls and space them out if possible.