Inventory 1.2.1

PROMOTIONAL PRODUCTS DATA INTERFACE SPECIFICATION FOR WEB SERVICES

PromoStandards Logo

Inventory Interface Standards

Version: 1.2.1

Date: 14-Apr-2015

Document Change Log

VersionDateReason for ChangeAuthor
.12014-2-10Initial DraftEric Shonebarger, CIO Hit Promotional Products
.22014-02-19Review by BIC Graphic personnel:
Removed authentication standard in lieu of all parties using following their standards.
Added ProductIDType to Request:
Added companion inventory to Reply:
Added multiple array detail fields
Tim Nale, Director IT BIC Graphic
.32014-03-03Modified Custom Attributes to ARRAY Added reference to Data Mining / AbuseTim Nale, Director IT BIC Graphic
1.02014-03-27Modified Quantity Available data type; added version controlTim Nale, Director IT BIC Graphic
1.0.02014-04-28Updated casing on field names and Array Naming conventionJon Norris, System Operations Manager Starline
1.2.02015-3-24Added Color, Size, and Generic Selection Criteria. Added controlled list of Error CodesTim Nale, Director IT BIC Graphic
1.2.12015-3-31Correct getFilterValue Request and Reply for proper naming of uniquenessTim Nale, Director IT BIC Graphic
1.2.12015-4-14Added entryType to ProductCompanionInventory documentation. This was already in WSDL just excluded from documentation.

Modified error code 115 to include "not"

Added error code 120: generic way to handle required fields

Added error code 125: generic way to handle "not supported" error messages

Corrected typo in field name to match WSDL in "GetFiltervaluesReply" from "filterSelectionsArray" to "filterSelectionArray"

Corrected typo in field name to match WSDL in "Request" from "filterSelectionsArray" to "filterSelectionArray"
Jon Norris, VP Operations, Starline

Abstract and Recommended Audience

This document describes the technologies for integration of suppliers and distributors in the Promotional Products Industry. This document will discuss in detail the technology required in order to build the interface. Additionally, this document will provide sample code in order to use the interface.

This document will assume that the reader is fluent in web based technologies, and has knowledge of the language they plan to consume the web service in.

Background Information

All specifications will be built using the Simple Object Access Protocol (SOAP) over HTTPS as the foundation for the web services protocol stack in order to provide a standards based secure form of communication.

More information on SOAP can be found at http://www.w3.org/TR/soap12-part1/ (opens in a new tab)

Previous Versions

Inventory 1.0.0 - replaced 04/01/2015:

View Documentation (opens in a new tab)

Inventory

There will be two functions available as part of this web service.

  • getFilterValues()
  • getInventoryLevels()

Function: getFilterValues()

This function is optional and can be called to get the List of Values that can be passed to the getInventoryLevels function to limit the result set.

GetFilterValuesRequest Object

FieldDescriptionData TypeRequired?
wsVersionThe Standard Version of the Web Service being referenced64 STRING: EnumeratedTRUE
idThe customerID or any other agreed upon ID.64 STRINGTRUE
passwordThe password associated with the customerID.64 STRINGFALSE
productIDItem's ID64 STRINGTRUE
productIDtypeproductID type (Distributor, Supplier)64 STRINGTRUE

GetFilterValuesReply Object

FieldDescriptionData TypeRequired?
productIDThe associated product.64 STRINGTRUE
filterColorArrayAn array of different selections the product is offered and can be provided as a filter to Inventory Service getInventoryLevels.256 STRING ARRAYFALSE
filterSizeArrayAn array of different selections the product is offered and can be provided as a filter to Inventory Service getInventoryLevels.256 STRING ARRAYFALSE
filterSelectionArrayAn array of different selections other than Color and Size the product is offered and can be provided as a filter to Inventory Service getInventoryLevels.256 STRING ARRAYFALSE
errorMessageResponse for any error requiring notification to requestor256 STRING: EnumeratedFALSE

Function: getInventoryLevels()

This function will provide the results of the current Inventory Levels for the product enquired filter by the criteria provided.

Request:

FieldDescriptionData TypeRequired?
wsVersionThe Standard Version of the Web Service being referenced64 STRING: EnumeratedTRUE
idThe customerID or any other agreed upon ID.64 STRINGTRUE
passwordThe password associated with the customerID.64 STRINGFALSE
productIDItem's ID64 STRINGTRUE
productIDtypeproductID type (Distributor, Supplier)64 STRINGTRUE
filterColorArrayAn array of different Colors the Inventory is requested256 STRING ARRAYFALSE
filterSizeArrayAn array of different Sizes the Inventory is requested256 STRING ARRAYFALSE
filterSelectionArrayAn array of different selections (generic) other than Color and Size the Inventory is requested256 STRING ARRAYFALSE

Reply:

FieldDescriptionData TypeRequired?
productIDThe associated product.64 STRINGTRUE
productVariationInventoryArrayAn array of inventory levels grouped by variation.ARRAYFALSE
productCompanionInventoryArrayArray of companion items' inventory levels.ARRAYFALSE
errorMessageResponse for any error requiring notification to requestor256 STRING: EnumeratedFALSE
CustomMessageArrayAn array of custom data that the supplier/distributor is free to implement in any way they see fit.ARRAYFALSE

ProductVariationInventory Object

FieldDescriptionData TypeRequired?
partIDThe associated part64 STRINGTRUE
partDescriptionPart's description256 STRINGFALSE
partBrandPart's brand64 STRINGFALSE
priceVarianceVariance from requested part's price64 STRINGFALSE
quantityAvailableThe quantity available64 STRINGTRUE
attributeColorDescription of the color of the part64 STRINGFALSE
attributeSizeDescription of the size of the part64 STRINGFALSE
attributeSelectionDescription of the generic selection criteria of the part64 STRINGFALSE
AttributeFlexArrayArray of the part's attributesARRAYFALSE
customProductMessageMessage from the supplier regarding the stock256 STRINGFALSE
entryTypeRecord type (exact, alternate)64 STRINGFALSE
validTimestampDatetime inventory is availableISO 8601FALSE

ProductCompanionInventory Object

FieldDescriptionData TypeRequired?
partIDThe companion part64 STRINGTRUE
partDescriptionPart's description256 STRINGFALSE
partBrandPart's brand64 STRINGFALSE
priceCompanion item price64 STRINGFALSE
quantityAvailableThe quantity available64 STRINGTRUE
attributeColorDescription of the color of the part64 STRINGFALSE
attributeSizeDescription of the size of the part64 STRINGFALSE
attributeSelectionDescription of the generic selection criteria of the part64 STRINGFALSE
entryTypeRecord type (exact, alternate)64 STRINGFALSE
AttributeFlexArrayArray of the part's attributesARRAYFALSE
customProductMessageMessage from the supplier regarding the stock256 STRINGFALSE
validTimestampDatetime inventory is availableISO 8601FALSE

CustomMessage Object

Suppliers and distributors are free to use the custom array however they wish.

AttributeFlex Object

FieldDescriptionData TypeRequired?
IDAttribute ID64 STRINGFALSE
NameAttribute Name64 STRINGFALSE
ValueAttribute Value256 STRINGFALSE

The Supplier can use this ARRAY to define additional unique attributes about the product. An example could be for an item which has choices about thickness which can be made.

In this ID = "1"; Name = "Thickness"; Value = "0.10 inches"

CustomProductMessage Object

Suppliers and distributors are free to use this custom message String however they wish.

Enumerated Type Restrictions

wsVersionThe Standard Version of the Web Service being referenced64 STRING: Enumerated1.0.0 1.2.1
errorMessageResponse for any error requiring
notification to requestor
256 STRING: Enumerated100: ID (customerID) not found
105: Authentication Credentials failed
110: Authentication Credentials required
115: wsVersion not found
120: The following field(s) are required [Comma Delimited field names]
125: Not Supported
200: ProductID not found
205: ProductColor not found
210: ProductSize not found
999: General Error – Contact the System Service Provider

Code Samples

To be published under separate specification: "Inventory Interface Supplier/Distributor Developer Guide"

Inventory Interface Supplier Developer Guide 1.2.1 (opens in a new tab)

DATA MINING / ABUSE GUIDELINE

The use of services detailed within this specification are to be conducted within the current guidelines of the "Interface Data Use Guidelines Standards"

Validation of Services

Before you publish your endpoint, please ensure that it adheres to the promostandards.org (opens in a new tab) spec by using the web service validation tool.

https://services.promostandards.org/webserviceValidator/home (opens in a new tab)

Select the service, version, method and input your endpoint. If the endpoint is correct you should receive a message of:

"The XML response is valid."

© 2021 PromoStandards

Diagrams

getFilterValues

getInventoryLevels