Skip to content

Product Identification API (1)

This API provides services to upload, manipulate and download Global Trade Item data in the CDQ Cloud

Download OpenAPI description
api-v1.json
api-v1.yaml
Languages
Servers
Mock server

https://developer.cdq.com/_mock/apis/product-identification-api/api-v1/

Production

https://api.cdq.com/product-identification/rest/

Global Trade Items

-> Covers several operations including the creation, reading, updating, and deletion of Global Trade Items, as well as the management of references between Global Trade Items and business partners. The endpoints under this tag are designed to handle data related to Global Trade Items, which are unique identifiers for products in the global marketplace.

Operations

List Global Trade Items

Request

Provide a list of Global Trade Items with optional filtering and pagination.

Security
apiKey
Query
startAfterstring

Use nextStartAfter provided in the response of previous call as an indicator for a next page.

Example: startAfter=NjI4ZGNkZjAzYjlkMjY4NjhlNjQxNDRm
limitinteger(int32)>= 1

Number of items to be returned on the page.

Default 500
Example: limit=500
businessPartnerIdsArray of strings(BusinessPartnerId)

Filter Global Trade Items by Business Partners ID that are referenced.

Example: businessPartnerIds=63e635235c06b7396330fe40
featuresOnArray of strings(GlobalTradeItemsReadFeatureParam)

Features to be turned on:

  • FETCH_BUSINESS_PARTNER_REFERENCES - Includes businessPartnerReferences. By default, turned off.
  • NUMBER_OF_TOTAL - Allows switching fetching the total number of Global Trade Items to improve performance. By default turned off.
Items Enum ValueDescription
FETCH_BUSINESS_PARTNER_RELATIONS

Includes businessPartnerReferences.

NUMBER_OF_TOTAL

Allows switching fetching the total number of Global Trade Items to improve performance.

Example: featuresOn=FETCH_BUSINESS_PARTNER_RELATIONS
curl -i -X GET \
  https://developer.cdq.com/_mock/apis/product-identification-api/api-v1/globaltradeitems \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
totalinteger(PageTotal)

Total number of items which can be paged.

Example: "67"
limitinteger(Limit)

Number of items per page.

Example: "100"
startAfterstring(StartAfter)

The ID which is used to read the page.

Example: "5712566172571652"
nextStartAfterstring(NextStartAfter)

Provides a value to be used as a startAfter in next page request.

Example: "5712566172571652"
valuesArray of objects(GlobalTradeItemSearchResult)

List of Global Trade Items.

Response
application/json
{
  "total": "67",
  "limit": "100",
  "startAfter": "5712566172571652",
  "nextStartAfter": "5712566172571652",
  "values": [
    { … }
  ]
}

Create Global Trade Item

Request

Provide a new Global Trade Item with unique GTIN and name.

Security
apiKey
Bodyapplication/jsonrequired
gtinstring(Gtin)required

A 13 digit Global Trade Item Number that uniquely identifies the item

Example: "5099206081901"
namestring(ItemName)required

Human readable name of the item.

Example: "Business Partner Update Browser"
curl -i -X POST \
  https://developer.cdq.com/_mock/apis/product-identification-api/api-v1/globaltradeitems \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "gtin": "5099206081901",
    "name": "Business Partner Update Browser"
  }'

Responses

OK

Bodyapplication/json
gtinstring(Gtin)

A 13 digit Global Trade Item Number that uniquely identifies the item

Example: "5099206081901"
namestring(ItemName)

Human readable name of the item.

Example: "Business Partner Update Browser"
businessPartnerReferencesArray of objects(BusinessPartnerReferenceSearchResult)

List of Business Partners that are referenced.

Response
application/json
{
  "gtin": "5099206081901",
  "name": "Business Partner Update Browser",
  "businessPartnerReferences": [
    { … }
  ]
}

Update Global Trade Items

Request

Allows updating the Global Trade Item.

Security
apiKey
Path
gtinstring(Gtin)required

Unique Global Trade Item Number.

Example: 5099206081901
Bodyapplication/jsonrequired
namestring(ItemName)

Human readable name of the item.

Example: "Business Partner Update Browser"
curl -i -X PATCH \
  https://developer.cdq.com/_mock/apis/product-identification-api/api-v1/globaltradeitems/5099206081901 \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "name": "Business Partner Update Browser"
  }'

Responses

OK

Bodyapplication/json
globalTradeItemobject(GlobalTradeItemUpdate)

Updates provided for a Global Trade Item.

statusstring(GlobalTradeItemUpdateResultStatus)

Status of the update operation:

  • OK - the global trade item has been updated
  • NOT_FOUND - the global trade item is not found
Example: "OK"
Response
application/json
{
  "globalTradeItem": {
    "name": "Business Partner Update Browser"
  },
  "status": "OK"
}

Read Global Trade Item

Request

Provide a single Global Trade Item with the given GTIN.

Security
apiKey
Path
gtinstring(Gtin)required

Unique Global Trade Item Number.

Example: 5099206081901
curl -i -X GET \
  https://developer.cdq.com/_mock/apis/product-identification-api/api-v1/globaltradeitems/5099206081901 \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
globalTradeItemobject(GlobalTradeItemSearchResult)

An item or product.

statusstring(GlobalTradeItemReadResultStatus)

Status of the read operation:

  • OK - the global trade item has been found
  • NOT_FOUND - the global trade item is not found
Example: "OK"
Response
application/json
{
  "globalTradeItem": {
    "gtin": "5099206081901",
    "name": "Business Partner Update Browser",
    "businessPartnerReferences": [ … ]
  },
  "status": "OK"
}

Delete Global Trade Items

Request

Delete multiple Global Trade Items by GTIN.

Security
apiKey
Bodyapplication/jsonrequired
globalTradeItemsArray of objects(GlobalTradeItemDelete)non-emptyrequired

List of Global Trade Items to be deleted.

globalTradeItems[].​gtinstring(Gtin)required

A 13 digit Global Trade Item Number that uniquely identifies the item

Example: "5099206081901"
curl -i -X POST \
  https://developer.cdq.com/_mock/apis/product-identification-api/api-v1/globaltradeitems/delete \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "globalTradeItems": [
      {
        "gtin": "5099206081901"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
resultsArray of objects(GlobalTradeItemDeleteResult)

List of Global Trade Items that have been deleted.

Response
application/json
{
  "results": [
    { … }
  ]
}

Create Global Trade Item Reference

Request

Create a reference between Global Trade Item and Business Partner.

Security
apiKey
Path
gtinstring(Gtin)required

Unique Global Trade Item Number.

Example: 5099206081901
Bodyapplication/jsonrequired
businessPartnerReferencesArray of objects(BusinessPartnerReferenceCreate)<= 30 itemsrequired

List of Business Partners to be referenced.

businessPartnerReferences[].​storageIdstring(BusinessPartnerStorageId)required

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
businessPartnerReferences[].​dataSourceIdstring(BusinessPartnerStorageDataSourceId)required

Unique identifier for a Data Source of the Storage.

Example: "648824a691d8d2503d65103e"
businessPartnerReferences[].​businessPartnerIdstring(BusinessPartnerId)required

A CDQ ID identifies a business partner uniquely in the context of the Corporate Data League.

Example: "63e635235c06b7396330fe40"
businessPartnerReferences[].​externalIdstring(BusinessPartnerExternalId)

Arbitrary identifier type to mark customer IDs that are "external" from CDQ's perspective. This is the identifier a customer provides to identify its records.

Example: "The ID managed in the customer's SAP systems."
curl -i -X POST \
  https://developer.cdq.com/_mock/apis/product-identification-api/api-v1/globaltradeitems/5099206081901/businesspartnerreferences \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "businessPartnerReferences": [
      {
        "storageId": "72d6900fce6b326088f5d9d91049e3e6",
        "dataSourceId": "648824a691d8d2503d65103e",
        "businessPartnerId": "63e635235c06b7396330fe40",
        "externalId": "The ID managed in the customer'\''s SAP systems."
      }
    ]
  }'

Responses

OK

Bodyapplication/json
resultsArray of objects(BusinessPartnerReferenceCreateResult)

List of Business Partner References that have been created.

Response
application/json
{
  "results": [
    { … }
  ]
}

Delete Global Trade Item References

Request

Delete references between Global Trade Item and Business Partner.

Security
apiKey
Path
gtinstring(Gtin)required

Unique Global Trade Item Number.

Example: 5099206081901
Bodyapplication/jsonrequired
businessPartnerReferencesArray of objects(BusinessPartnerReferenceDelete)<= 30 itemsrequired

List of Business Partner References to be deleted.

businessPartnerReferences[].​storageIdstring(BusinessPartnerStorageId)required

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
businessPartnerReferences[].​businessPartnerIdstring(BusinessPartnerId)required

A CDQ ID identifies a business partner uniquely in the context of the Corporate Data League.

Example: "63e635235c06b7396330fe40"
curl -i -X POST \
  https://developer.cdq.com/_mock/apis/product-identification-api/api-v1/globaltradeitems/5099206081901/businesspartnerreferences/delete \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "businessPartnerReferences": [
      {
        "storageId": "72d6900fce6b326088f5d9d91049e3e6",
        "businessPartnerId": "63e635235c06b7396330fe40"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
resultsArray of objects(BusinessPartnerReferenceDeleteResult)

List of Business Partner References that have been deleted.

Response
application/json
{
  "results": [
    { … }
  ]
}