Promotional Products Data Interface Specification for Web services

 

 

 

Product Compliance 1.0.0

 

 


 

Version: 1.0.0

Date: 2020-01-08

Document Change Log

Version

Date

Reason for Change

Author

1.0.0

01/08/2020

Production Release

Dustin Kessler, Enterprise Architect, Staples Promotional Products

 

 

 

 

 

 

 

 

Contributors

The following have contributed to the creation of this specification:

Contributors:      Dustin Kessler, Enterprise Architect, Staples Promotional Products
                              Max Stepanskiy, Executive Director of Enterprise Architecture, Advertising Specialty Institute

                              Eric Shonebarger, CIO, Hit Promotional Products, Inc

                              Michael J Plourde, Director Data and Analytics, Geiger
                                              

                             

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 to build the interface. Additionally, this document will provide sample code 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 standard based on a secure form of communication.

More information on SOAP can be found at http://www.w3.org/TR/soap12-part1/

 

 

 


 

Service Details

 

Function: getProductsWithRegulations ()

Gets the list of products and optional parts which currently or in the future will have applicable regulations

Request:GetProductsWithRegulationsRequest

Field

Description

WSDL Data Type

SQL Data Type

Required?

wsVersion

The Standard Version of the Web Service being referenced. Values are enumerated {1.0.0}

STRING

VARCHAR(64)

TRUE

id

The customerId or any other agreed upon Id.

STRING

VARCHAR(64)

TRUE

password

The password associated with the customerId.

STRING

VARCHAR(64)

FALSE

changeTimeStamp

Beginning date time since last change in UTC; this element being left off the request indicates an intention to get all whereas including this element in the request indicates an intention to only get those that have changed since the supplied date and time.

ISO 8601 DATE

DATETIME

FALSE

 

Reply: GetProductsWithRegulationsResponse

Field

Description

WSDL Data Type

SQL Data Type

Required?

productWithRegulationsArray

The list of products and optional their parts which currently or in the future will have applicable regulations

OBJECT ARRAY

OBJECT ARRAY

TRUE

ServiceMessageArray

Error message object Array

OBJECT ARRAY

OBJECT ARRAY

FALSE

 

 

 

 

ProductWithRegulations Object

Field

Description

WSDL Data Type

SQL Data Type

Required?

productId

The identifier of the product that has or will have applicable regulations

STRING

VARCHAR(64)

TRUE

partId

The identifier of the part that has or will have applicable regulations; this element being left off the response indicates all parts have or will have applicable regulations whereas including this element in the response indicates this part has or will have applicable regulations

STRING

VARCHAR(64)

FALSE

complianceGroups

The list of promo standards compliance groups which currently or in the future apply to this product and, if included in the response, part
Values are enumerated {CaliforniaProp65}

ENUMERATED STRING ARRAY

VARCHAR(64) ARRAY

TRUE

 

Function: getCompliance ()

Gets the compliance data of the specific product and part, if supplied, for the CaliforniaProp65 compliance group.

Request:GetComplianceRequest

Field

Description

WSDL Data Type

SQL Data Type

Required?

wsVersion

The Standard Version of the Web Service being referenced. Values are enumerated {1.0.0}

STRING

VARCHAR(64)

TRUE

id

The customer Id or any other agreed upon Id.

STRING

VARCHAR(64)

TRUE

password

The password associated with the Id.

STRING

VARCHAR(64)

FALSE

productId

The identifier of the product to get compliance data for

STRING

VARCHAR(64)

TRUE

partId

The identifier of the part to get compliance data for; this element being left off indicates an intention to get compliance data on any applicable parts for the specific product whereas including this element indicates an intention to only get compliance data for the specific part

STRING

VARCHAR(64)

FALSE

 

 

 

 

Reply: GetComplianceResponse

Field

Description

WSDL Data Type

SQL Data Type

Required?

ComplianceData

An object containing the compliance data for a product; this element being left off indicates no compliance data is available for the requested product or, if requested, part.

OBJECT

OBJECT

FALSE

ServiceMessage

Service message object

OBJECT

OBJECT

FALSE

 

ComplianceData

Field

Description

WSDL Data Type

SQL Data Type

Required?

productId

The identifier of the product associated with the compliance data

STRING

VARCHAR(64)

TRUE

partId

The identifier of the part associated with the compliance data; this element being left off indicates the compliance data applies to all parts whereas including this element in the response indicates the compliance data is for the part

STRING

VARCHAR(64)

FALSE

CAProp65

An object containing the CaliforniaProp65 compliance data for a product; this element being left off indicates no compliance data is available for the requested product or, if requested, part.

OBJECT

OBJECT

FALSE

 

 


 

CAProp65

Field

Description

WSDL Data Type

SQL Data Type

Required?

ApplicableWarnings

The warning(s) which apply to the product, or if specified in the response, part

OBJECT ARRAY

OBJECT ARRAY

TRUE

policyForApplyingLabel

The trigger for applying the warning label to the product or product packaging
Values are enumerated {Applied Upon Request, Applied When Shipping to California, Applied Always}

ENUMERATED STRING

VARCHAR(64)

TRUE

 

 

CAProp65Warning

Field

Description

WSDL Data Type

SQL Data Type

Required?

applicableWarning

A warning that applies to the product, or if specified in the response, part
Values are enumerated {On Product Cancer, On Product Reproductive, Food, Furniture, Alcoholic Beverage}

ENUMERATED STRING

VARCHAR(64)

TRUE

applicableChemicals

The chemicals used on or in the product, or if specified in the response, part, that cause the warning to apply to the product or part

STRING ARRAY

STRING ARRAY

FALSE

warningLabelApplied

The type of warning label applied to the product or product packaging
Values are enumerated {Short Form, Long Form}

ENUMERATED STRING

VARCHAR(64)

TRUE

 

 


 

Appendix A: Error Messages

ServiceMessage

Field

Description

WSDL Data Type

SQL Data Type

Required?

code

The numerical value of the code

INT

INT

TRUE

description

Response for any message requiring notification to requestor

STRING

VARCHAR(256)

TRUE

severity

The severity of the message.  Values are enumerated: {Error, Information, Warning}

ENUMERATED STRING

VARCHAR(64)

TRUE

 

Standardized Codes:  The range of 100-199 has been reserved for standardized error codes.  The number 999 has been reserved for an error codes that is a “General Error - Contact System Service Provider”

Code

Description

100

ID (customerID) not found

104

This account is unauthorized to use this service.  Please contact the service provider

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: [details]

999

General Error – Contact the System Service Provider Details: [Details]

 

 

Service Specific Code: These error codes are only for this service.

Code

Description

600

Product Id not found

610

Data violation: {0} 

 

(Occurs when a supplier does a pre-check on the data and finds that there is a mismatch of data and/or there are incorrect calculations)

620

Field is not supported: {0}

630

Part Id not found

 

10/23/2019

 

PromoStandards Launches Significant Improvement to Product Data Standard

 

PromoStandards has enhanced the Product Data integration standard that simplifies the implementation and increases the value to both distributors and suppliers. The enhanced Product Data service provides a standardized way to electronically share product information that previously was only available in proprietary or printed forms. The standard allows suppliers to quickly publish product information to distributors who are using the product data for publishing products to external websites as well as internal systems including ERP and order entry systems.  This enhanced standard will significantly accelerate a distributors ability to launch new products and send cleaner orders to suppliers.

 

6 of the top 7 promotional products suppliers representing $5.4 billion in annual sales are among the suppliers who adopted the PromoStandards Product Data Standard.

 

The enhanced Product Data 2.0 standard makes several key improvements:

·        Primary Image URL provides a path to the default image for the product, which previously required the Media Content.

·        Pricing, including blank and decorated pricing, quantity-based pricing, and discount codes, is now included.  Pricing previously was available only via the Product Pricing & Configuration.

·        Imprint details including the default imprint location and decoration method information is now included, as well as the maximum number of imprint colors. Complete configuration details are available through the Product Pricing & Configuration.

·        Improved color support for clarity and convenience colors can now be expressed as a standard color name, such as “green,” in addition to a Hex or Pantone color, such as “PMS 361.” Distributors can much more readily identify the colors available because they no longer need to look up Hex or Pantone codes.

·        Compliance information is noted. Products that have related compliance information such as product safety will be marked as such to let data consumers know compliance information is available for the product. Detailed compliance information is to be included in a future standard.

 

“At the PPAI Expo we asked participants what they would like to see from PromoStandards in 2019. The overwhelming response was for concise product data that can be readily consumed for ecommerce shared Eric Shonebarger, PromoStandards Standards Committee Chairman, Board Member, and CIO of Top 10 supplier Hit Promotional Products. “We knew our number one goal for 2019 was to deliver based on community feedback.”

 

Said Dale Denham, PromoStandards Board Member and Senior Vice President/CIO of Top 10 distributor Geiger. “Product Data 2.0 is a game changer for Geiger and Crestline.  We are able to launch new products from participating suppliers to our 300+ Geiger and Crestline websites the day after a supplier publishes them to us.  We also are using this data for our order entry systems which improves the quality of the orders we send to suppliers. We’re excited to continue to leverage the constantly improving PromoStandards specifications to improve our business operations.”

 

“This service has been a long time coming and will add immediate value to any distributor or service provider looking for real time and accurate data to populate websites” Said Jon Norris, VP of Operations for Starline and Chair of PromoStandards.  “We were diligent to get the communities feedback and  deliver the right pieces of data that the industry needs to better connect the supply chain.  I am very happy where we ended up.  Now it’s go time”

 

To view the technical specifications on this new service please visit: PromoStandards.org

 

About PromoStandards
PromoStandards is a dedicated group of distributors, suppliers, and service provider visionaries committed to improving supply chain efficiency in the promotional products industry. The group creates and publishes integration standards that assists trading partners to electronically integrate for more efficient transactions and supply chain. PromoStandards includes Inventory Availability, Order Status, Order Shipment Notification, Product Data Media Content, Product Pricing & Configuration, Purchase Orders, and Invoices.

 

Promotional Products Data Interface Specification for Web services

 

 


 

            Product Data 2.0.0




Document Change Log

Version

Date

Reason for Change

Authors

2.0.0

10/23/2019

Initial Release

See Contributors

 

Contributors

The following have contributed to the creation of this specification:

 

Contributors: 

• Paul Fleischman, Technical Lead, PCNA

• Jon Norris, VP of Operations, Starline

• Tim Dietrich, PromoStandards Consultant

• Raj Mukherjee, Director of Integrations And ERP at Hit Promotional Products

• Mike Olivieri, Manager of Integrations and Web Applications at BIC Graphic North America

• Max Stepanskiy, Executive Director, Enterprise Architecture at Advertising Specialty Institute

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/

 


 

 

Product Data

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

getProduct()

getProductDateModified()

getProductCloseOut()

getProductSellable()

 

Function: getProduct()

This function will provide the detail product data based on a specific ProductId or any additional optional subset filtering provided at the request.

Request: GetProductRequest

Field

Description

Data Type

Required?

wsVersion

The Standard Version of the Web Service being referenced.  Values are enumerated {1.0.0}

64 STRING

TRUE

id

The customer Id or any other agreed upon Id.

64 STRING

TRUE

password

The password associated with the Id

64 STRING

FALSE

localizationCountry

ISO 3166-1 Alpha 2 code for Country

Example: CA=Canada;

                  US=United States

2 STRING

TRUE

localizationLanguage

ISO 639-1 Alpha 2 code for Language

Example: en = English;

                   fr = French

2 STRING

TRUE

productId

Item’s ID

64 STRING

TRUE

partId

The Supplier specific PartId; commonly referred to as a sku

64 STRING

FALSE

 

 

 

 

colorName

A specific part color for this product

64 STRING

FALSE

ApparelSizeArray

Used for returning specific apparel sizes.  Array of ApparelSize objects.

 

ARRAY

FALSE

 

Reply: GetProductResponse

Field

Description

Data Type

Required?

Product

Product Information

OBJECT

FALSE

ServiceMessageArray

An array of ServiceMessage objects.

ARRAY

FALSE

 

 

 

 

Product Object

Field

Description

Data Type

Required?

productId

The associated product.

64 STRING

TRUE

productName

The Supplier name for the product

256 STRING

TRUE

LocationDecorationArray

An array of Location Decoration objects

OBJECT ARRAY

TRUE

description

Basic product description or bulleted list of descriptions.

2048 STRING ARRAY

TRUE

priceExpiresDate

The date that the pricing in the ProductPriceGroupArray portion of the response expires.

 ISO 8601 DATE

 FALSE

ProductMarketingPointArray

Marketing points type and content.  An array of MarketingPoint objects.

OBJECT ARRAY

FALSE

ProductKeywordArray

Array of keywords often used in searching for this product.  An array of ProductKeyword objects.

OBJECT ARRAY

FALSE

productBrand

The specific product brand

64 STRING

FALSE

export

Product status for export

NILLABLE BOOLEAN

TRUE

ProductCategoryArray

The product’s categorization array.  An array of ProductCategory objects.

OBJECT ARRAY

FALSE

RelatedProductArray

Products related to the quested product as Substitutable, CompanionSell, or Common Grouping (Family).  An array of RelatedProduct objects.

OBJECT ARRAY

FALSE

ProductPartArray

All part specific product data.  An array of ProductPart objects. 

OBJECT ARRAY

TRUE

lastChangeDate

The date time stamp of the most recent change to this data in ISO 8601 format

ISO 8601 DATE

TRUE

creationDate

The date time stamp when this products data initially became available in ISO 8601 format

ISO 8601 DATE

TRUE

endDate

The Date this Product expires from Supplier availability in ISO 8601 format

ISO 8601 DATE

FALSE

effectiveDate

The Date this Product initially becomes available from the Supplier in ISO 8601 format

ISO 8601 DATE

FALSE

isCaution

Cautionary status to review for specific warnings about using product data.

NILLABLE BOOLEAN

TRUE

cautionComment

Product cautionary comments

1024 STRING

FALSE

isCloseout

Indicates if the product is a closeout

NILLABLE BOOLEAN

TRUE

lineName

Line Name / Division to which this product belongs

64 STRING

FALSE

primaryImageURL

The URL of the product’s primary image. Any valid URL can be returned including prefixes like http and ftp.

1024 STRING

FALSE

ProductPriceGroupArray

Marketing-oriented pricing information. Represented as an array of Product Price objects. Prices are List prices.

OBJECT ARRAY

FALSE

complianceInfoAvailable

Indicates if there is information about this product via the Product Safety & Compliance service.

NILLABLE BOOLEAN

FALSE

unspscCommodityCode

The United Nations Standard Products and Services Code® (UNSPSC®) that best describes this product. Note that the enumerated values are the UNSPSC "Commodity" codes. For more information, refer to https://www.unspsc.org.

INT

FALSE

imprintSize

The imprint Size

256 STRING

FALSE

defaultSetUpCharge

The default setup charge for this product. Can be a textual description.

STRING 1024

FALSE

defaultRunCharge

The default RUN charge for this product. Can be a textual description.

STRING 1024

FALSE

FobPointArray

An array of FOB points object

ARRAY

TRUE

 

 

 

 

 

         

 

LocationDecoration Object

Field

Description

Data Type

Required?

locationName

Location name

255 STRING

TRUE

maxImprintColors

The maximum number of imprint colors available, based on a decoration location and type.

INTEGER

FALSE

decorationName

Decoration name

64 STRING

TRUE

locationDecorationComboDefault

Is this the default location

BOOLEAN

TRUE

priceIncludes

Does this include price

BOOLEAN

TRUE

 

 

FobPoint Object

Field

Description

Data Type

Required?

fobId

The Id of the FOB Point

STRING VARCHAR(64)

       TRUE

fobPostalCode

The Postal or Zip Code of the fob Point

STRING VARCHAR(64)

TRUE

fobCity

The city of the FOB Point

STRING VARCHAR(64)

TRUE

fobState

The state of the FOB Point in ISO 3166-2 format.

STRING VARCHAR(64)

TRUE

fobCountry

The country of the FOB Point in Alpha 2 ISO3166 “CODE” format.

STRING VARCHAR(64)

 

TRUE

 

 

 

 

ProductCategory Object

Field

Description

Data Type

Required?

category

Product category

256 STRING

TRUE

subCategory

Product subcategory

256 STRING

FALSE

 

 

 

 

 

ProductMarketingPoint Object

Field

Description

Data Type

Required?

pointType

Basic category or type of marketing point being made.  e.g. Highlights, Size, Safety

64 STRING

FALSE

pointCopy

Marketing bullet or point copy

1024 STRING

TRUE

 

ProductKeyword Object

Field

Description

Data Type

Required?

keyword

A product keyword commonly utilized for search or other functions

16384 STRING

TRUE

 

 

 

RelatedProduct Object

Field

Description

Data Type

Required?

relationType

The relationship type between two products

64 STRING

TRUE

productId

Product Id

64 STRING

TRUE

partId

Part specific Id

64 STRING

FALSE

 

 

ProductPart Object

Field

Description

Data Type

Required?

partId

The part Id

64 STRING

TRUE

description

Description

2048 STRING

ARRAY

FALSE

countryOfOrigin

Country of Origin

ISO 3166-1 Alpha 2 code for Country

Example: CA=Canada;

                  US=United States

2 STRING

FALSE

ColorArray

Information about the part colors

OBJECT ARRAY

FALSE

primaryMaterial

Primary material of construction

64 STRING

FALSE

SpecificationArray

Specifications

OBJECT ARRAY

FALSE

shape

General shape

64 STRING

FALSE

ApparelSize

Used to describe an apparel size

OBJECT

FALSE

Dimension

Physical dimensions and weight

OBJECT

FALSE

leadTime

Lead time in days

INT

FALSE

unspsc

United Nations Standard Products and Services Code (UNSPSC)

8 STRING

FALSE

gtin

Global Trade Item Number (GTIN)

14 STRING

FALSE

isRushService

Rush service

NILLABLE BOOLEAN

TRUE

ProductPackagingArray

Packaging option details; e.g. Gift Box, Cello Pack, Sleeve.  An array of ProductPackaging objects.

OBJECT ARRAY

FALSE

ShippingPackageAgive rray

Shipping package option details for the partPackaging Default package type; e.g. Carton, Box, Pallet.  An array of ShippingPackage objects.

OBJECT ARRAY

FALSE

endDate

The date this part expires from supplier availability in ISO 8601 format

ISO 8601 DATE

FALSE

effectiveDate

The Date this Part initially becomes available from the Supplier in ISO 8601 format

ISO 8601 DATE

FALSE

isCloseout

Indicates if a closeout

NILLABLE BOOLEAN

TRUE

isCaution

Cautionary status to review for specific warnings about using product data

NILLABLE BOOLEAN

TRUE

cautionComment

Cautionary comments

1024 STRING

FALSE

nmfcCode

National Motor Freight Classification Code

DECIMAL

FALSE

nmfcDescription

National Motor Freight Classification Description

1024 STRING

FALSE

nmfcNumber

National Motor Freight Classification Number

64 STRING

FALSE

isOnDemand

Manufactured on demand / Made to order

NILLABLE
BOOLEAN

TRUE

isHazmat

Contains hazardous material.  A nil value indicates this it is unknown or the data is not available by the supplier.

NILLABLE

BOOLEAN

TRUE

primaryColor

The "go to market" color. Represented as a Color Object.

OBJECT

FALSE

 

Color Object

Field

Description

Data Type

Required?

colorName

Supplier specific color name.  Go to market color

64 STRING

TRUE

hex

The HEX code representation.  This is not a supplement for product color but data used for generating web user interfaces.

64 STRING

FALSE

approximatePms

The PMS code representation.  This is not a supplement for product color.

64 STRING

FALSE

standardColorName

The standard color that best describes this color. Eventually may become an enumeration.

64 STRING

FALSE

Product Price Group Object

Field

Description

Data Type

Required?

groupName

Price group description

64 STRING

TRUE

currency

The currency supported in ISO4217 format.

64 STRING

TRUE

description

The description of the product price

2028 STRING

FALSE

ProductPriceArray

An array of Product Price objects

ARRAY

TRUE

 

 

 

 

 

 

Product Price  Object

Field

Description

Data Type

Required?

quantityMax

The maximum quantity for which this price applies.

INT

TRUE

quantityMin

The minimum quantity for which this price applies.

INT

TRUE

price

The price value.

DECIMAL

TRUE

discountCode

The discount code.

5 STRING

FALSE

 

 

 

Specification Object

Field

Description

Data Type

Required?

specificationType

The type of specification

64 STRING FACIT

TRUE

specificationUom

Specification unit of measure  

64 STRING

TRUE

measurementValue

Specification Measurement Value

64 STRING

TRUE

 

ApparelSize Object

Field

Description

Data Type

Required?

apparelStyle

Apparel style

64 STRING FACIT

TRUE

labelSize

The apparel items tagged size.  e.g. XS, S, M, L, etc.

6 STRING FACIT

TRUE

customSize

Used to communicate custom size when labelSize is CUSTOM.

64 STRING

FALSE

 

Dimension Object

Field

Description

Data Type

Required?

dimensionUom

The dimensional unit of measure

2 STRING FACIT

TRUE

depth

The depth/length of the part using the unit of measure specified in dimensionUom

DECIMAL

FALSE

height

The height of the part using the unit of measure specified in dimensionUom

DECIMAL

FALSE

width

The width of the part using the unit of measure specified in dimensionUom

DECIMAL

FALSE

weightUom

The weight unit of measure for the part

2 STRING FACIT

TRUE

weight

The weight of the part using the unit of measure specified in dimensionUom

DECIMAL

FALSE

 

ProductPackaging Object

Field

Description

Data Type

Required?

default

Boolean flag identifying the single default packaging for this package

BOOLEAN

TRUE

packageType

The packaging specific type for this partId e.g. Gift Box, Cello Pack, Sleeve

256 STRING

TRUE

description

The Packaging specific description

2048 STRING

FALSE

quantity

The partId unit Quantity included within this specific Packaging Option

DECIMAL

TRUE

dimensionUom

The unit of measure for the package

2 STRING FACIT

TRUE

depth

The depth/length of the package in the dimensionUom unit of measure

DECIMAL

FALSE

height

The height of the package in the dimensionUom unit of measure

DECIMAL

FALSE

width

The width of the package in the dimensionUom unit of measure

DECIMAL

FALSE

weightUom

The weight unit of measure for the packageType

2 STRING FACIT

TRUE

weight

The weight of the specific packageType

DECIMAL

FALSE

 

ShippingPackage Object

Field

Description

Data Type

Required?

packageType

The shipping package specific type for this shipping package e.g. Box, Carton, etc.

256 STRING

TRUE

description

The shipping package specific description

2048 STRING

FALSE

quantity

The partId unit quantity included within this specific shipping packaging option

DECIMAL

TRUE

dimensionUom

The weight unit of measure for the packageType

2 STRING FACIT

TRUE

depth

The depth/length of the shipping package in the dimensionUom unit of measure

DECIMAL

FALSE

height

The height of the shipping package in the dimensionUom unit of measure

DECIMAL

FALSE

width

The width of the shipping package in the dimensionUom unit of measure

DECIMAL

FALSE

weightUom

The weight unit of measure for the packageType

2 FACIT STRING

TRUE

weight

The weight of the specific packageType

DECIMAL

FALSE

 

getProductDateModified()

This function will provide the list of Product Ids and optional Part Ids for all items which have changed since the date supplied in the request.

Request: GetProductDateModifiedRequest

Field

Description

Data Type

Required?

wsVersion

The Standard Version of the Web Service being referenced.  Values are enumerated {1.0.0}

64 STRING

TRUE

id

The customer Id or any other agreed upon Id.

64 STRING

TRUE

password

The password associated with the Id

64 STRING

FALSE

changeTimeStamp

Beginning date time since last change in UTC

ISO 8601 DATE

TRUE

 

Reply: GetProductDateModifiedResponse

Field

Description

Data Type

Required?

ProductDateModifiedArray

Array listing of all Product and Part specific Ids which have changed since the reference date requested (lastChangeDate).  An array of ProductChange objects.

OBJECT ARRAY

TRUE

ServiceMessageArray

An array of ServiceMessage objects.

ARRAY

FALSE

 

ProductDateModified Object

Field

Description

Data Type

Required?

productId

The associated product

64 STRING

TRUE

partId

The associated part

64 STRING

FALSE

 

 

getProductCloseOut()

This function will provide a list of Product Ids and optional Part Ids for all items which currently have an isCloseOut value of TRUE.

Request: GetProductCloseOutRequest

Field

Description

Data Type

Required?

wsVersion

The Standard Version of the Web Service being referenced. Values are enumerated {1.0.0}

64 STRING

TRUE

id

The customer Id or any other agreed upon Id.

64 STRING

TRUE

password

The password associated with the Id

64 STRING

FALSE

 

 

 

Reply: GetProductCloseOutResponse

Field

Description

Data Type

Required?

ProductCloseOutArray

All product and part specific Ids which are on closeout.  An array of ProductCloseOut objects.

OBJECT ARRAY

FALSE

ServiceMessageArray

An array of ServiceMessage objects.

ARRAY

FALSE

 

ProductCloseOut Object

Field

Description

Data Type

Required?

productId

The associated product

64 STRING

TRUE

partId

The associated part

64 STRING

FALSE

 

 

 

 

 

getProductSellable()

This function will provide a list of Product Ids and optional Part Ids along with their status of available to sell (Sellable TRUE or FALSE).

Request: GetProductSellableRequest

Field

Description

Data Type

Required?

wsVersion

The Standard Version of the Web Service being referenced.  Values are enumerated {1.0.0}

64 STRING

TRUE

id

The customer Id or any other agreed upon Id.

64 STRING

TRUE

password

The password associated with the Id

64 STRING

FALSE

productId

The associated product

64 STRING

FALSE

partId

The associated part

64 STRING

FALSE

localizationCountry

ISO 3166-1 Alpha 2 code for Country

Example: CA=Canada;

                  US=United States

2 STRING

TRUE

localizationLanguage

ISO 639-1 Alpha 2 code for Language

Example: en = English;

                   fr = French

2 STRING

TRUE

lineName

The line name (ex : Trimark, Hit)

64 STRING

FALSE

isSellable

Indicates if sellable

BOOLEAN

TRUE

 

 

 

 

 

Reply: GetProductSellableResponse

Field

Description

Data Type

Required?

ProductSellableArray

Array listing of all product and part specific Ids along with sellable status.  An array of ProductSellable objects.

OBJECT ARRAY

TRUE

ServiceMessageArray

An array of ServiceMessage objects.

ARRAY

FALSE

 

ProductSellable Object

Field

Description

Data Type

Required?

productId

The associated product

64 STRING

TRUE

partId

The associated part

64 STRING

FALSE

culturePoint

The culture point

64 STRING

FALSE

 

 

 


 

Enumerated Type Restrictions

 

wsVersion

The Standard Version of the Web Service being referenced

64 STRING FACIT

1.0.0

dimensionUom

The dimensional unit of measure

64 STRING FACIT

MM (Millimeter)

CM (Centimeter)

MR (Meter)

IN (Inch)

FT (Feet)

YD (Yards)

weightUom

The weight unit of measure

2 STRING FACIT

ME (Milligram)

KG (Kilogram)

OZ (Ounce)

LB (Pound)

relationType

The relationship type between the two products

64 STRING FACIT

Substitute

Companion Sell

Common Grouping

specificationType

List of possible values.  The type of specification.

64 STRING FACIT

Length

Thickness

Radius

Volume

Capacity

Memory

Data Ports

Capacitance

Voltage

Point Size

Sheet Size

Sheet Count

Pockets

Inseam

Bust

Chest

Waist

Hips

Cup

Rise

Neck

Thigh

Shoulders

Sleeve

Device Size

apparelStyle

List of possible values. e.g. Ladies, Men, Youth, etc.

64 STRING FACIT

Unisex

Youth

Girls

Boys

Womens

WomensTall

Mens

MensTall

labelSize

List of possible values.  The apparel items tagged size. e.g. XS, S, M, XL, etc.

4 STRING FACIT

OSFA (One Size Fits All)

4XS (4 Extra Small)

3XS (3 Extra Small)

2XS (2 Extra Small)

XS (Extra Small)

S

M

L

XL (Extra Large)

2XL (2 Extra Large)

3XL (3 Extra Large)

4XL (4 Extra Large)

5XL (5 Extra Large)

CUSTOM

 

 

 

 

 

ServiceMessage Object

Field

Description

Data Type

Required?

code

The numerical value of the code

INT

TRUE

description

Response for any message requiring notification to requestor

STRING

VARCHAR(256)

TRUE

severity

The severity of the message.  Values are enumerated: {Error, Information, Warning}

ENUMERATED STRING

VARCHAR(256)

TRUE

 

Standardized Codes:  The range of 100-199 has been reserved for standardized error codes.  The number 999 has been reserved for an error codes that is a “General Error - Contact System Service Provider”

 

Code

Description

100

ID (customerID) not found

104

This account is unauthorized to use this service.  Please contact the service provider

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: [details]

130

Product Id not found

135

Product color not found

140

Part Id not found

145

Part color not found

150

Part size not found

999

General Error – Contact the System Service Provider

 

 

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 spec by using the web service validation tool. 

https://services.promostandards.org/webserviceValidator/home

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." 

 

 

 

This is a test page!

Promotional Products Data Interface Specification for Web services

 

 

 

Product Configuration, Decoration, and Pricing

 

 

Version:                1.0.0

Date:                                2017-07-19

Document Change Log

Version

Date

Reason for Change

Author

1.0.0

07/19/17

Initial Release

Design:                

Eric Shonebarger, CIO Hit Promotional Products, Inc

Eric Alessi, Essent Corporation

 

Contributors:    

Paul Fleischman, Technical Lead PCNA

Jon Norris, VP of Operations, Starline

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Contributors

The following have contributed to the create on this specification:

Design:                 Eric Shonebarger, CIO Hit Promotional Products, Inc

                                Eric Alessi, Essent Coporation

 

Contributors:    

                                Paul Fleischman, Technical Lead PCNA

                                Jon Norris, VP of 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/

 

 

 

 

 

Service Details

Function: getAvailableLocations()

This function will provide the names of locations for a given product.

Request: GetAvailableLocationsRequest

Field

Description

WSDL Data Type

SQL Data Type

Required?

wsVersion

The Standard Version of the Web Service being referenced. Values are enumerated {1.0.0}

STRING

VARCHAR(64)

TRUE

id

The customerId or any other agreed upon Id.

STRING

VARCHAR(64)

TRUE

password

The password associated with the customerId.

STRING

VARCHAR(64)

FALSE

productId

The product id for which to get the locations

STRING

VARCHAR(64)

TRUE

localizationCountry

ISO 3166-1 Alpha 2 code for Country Example: CA=Canada; US=United States

STRING

VARCHAR(2)

TRUE

localizationLanguage

ISO 639-1 Alpha 2 code for Language. Example: en = English; fr = French

STRING

VARCHAR(2)

TRUE

 

Reply: GetAvailableLocationsResponse

Field

Description

WSDL Data Type

SQL Data Type

Required?

AvailableLocationArray

An array of locations

ARRAY

ARRAY

TRUE

errorMessage999

List of possible values for errors. Values are enumerated—See Appendix A: Error Messages for full details.

STRING

VARCHAR(256)

FALSE

AvailableLocationArray

Field

Description

WSDL Data Type

SQL Data Type

Required?

locationId

A unique Id of the location

INT

INT

TRUE

locationName

The name of the location

STRING

VARCHAR(64)

TRUE

 

Function: getDecorationColors()

This function will be used to describe possible decoration colors given a productId.

Request: GetDecorationColorRequest

Field

Description

WSDL Data Type

SQL Data Type

Required?

wsVersion

The Standard Version of the Web Service being referenced. Values are enumerated: {1.0.0}

STRING

VARCHAR(64)

 

TRUE

id

The customerId or any other agreed upon Id.

STRING

VARCHAR(64)

TRUE

password

The password associated with the customerId.

STRING

VARCHAR(64)

 

FALSE

locationId

The Id of the location

INT

INT

TRUE

productId

ProductId to filter down to a specific product. If left blank, the function will return all decoration colors for all products.

STRING

VARCHAR(64)

TRUE

decorationId

The Id of the decoration to filter requests by

INT

INT

FALSE

localizationCountry

ISO 3166-1 Alpha 2 code for Country Example: CA=Canada; US=United States

STRING

VARCHAR(2)

TRUE

localizationLanguage

ISO 639-1 Alpha 2 code for Language. Example: en = English; fr = French

STRING

VARCHAR(2)

TRUE

 

GetDecorationColorResponse

Field

Description

WSDL Data Type

SQL Data Type

Required?

DecorationColors

The object with decoration colors

ARRAY

ARRAY

TRUE

errorMessage999

List of possible values for errors. Values are enumerated—See Appendix A: Error Messages for full details.

STRING

VARCHAR(256)

FALSE

 

 

 

 

DecorationColors

Field

Description

WSDL Data Type

SQL Data Type

Required?

ColorArray

An array of colors

ARRAY

ARRAY

TRUE

productId

The Id of the product.

STRING

VARCHAR(64)

TRUE

locationId

The Id of the location that was provided

STRING

VARCHAR(64)

TRUE

DecorationMethodArray

An array of decoration methods for the location

ARRAY

ARRAY

TRUE

pmsMatch

TRUE, if PMS match is possible

BOOLEAN

BOOLEAN

TRUE

fullColor

Set to true if the decoration method is full color process; False implies that number of colors is irrelevant.

BOOLEAN

BOOLEAN

TRUE

 

ColorArray

Field

Description

WSDL Data Type

SQL Data Type

Required?

colorId

A unique Id of the color of the imprint

INT

INT

TRUE

colorName

The name of the imprint color

STRING

VARCHAR(64)

TRUE

DecorationMethodArray

Field

Description

WSDL Data Type

SQL Data Type

Required?

decorationId

A unique Id of the decoration

INT

INT

TRUE

decorationName

The name of the decoration

STRING

VARCHAR(64)

TRUE

 

Function: getFobPoints()

This function will return basic information about FOB points for a given product.

Request: GetFobPointsRequest

Field

Description

WSDL Data Type

SQL Data Type

Required?

wsVersion

The Standard Version of the Web Service being referenced. Values are enumerated: {1.0.0}

STRING

VARCHAR(64)

TRUE

id

The customerId or any other agreed upon Id.

STRING

VARCHAR(64)

TRUE

password

The password associated with the customerId.

STRING

VARCHAR(64)

FALSE

productId

The productId you are requesting FOB points for

STRING

VARCHAR(64)

FALSE

localizationCountry

ISO 3166-1 Alpha 2 code for Country Example: CA=Canada; US=United States

STRING

VARCHAR(2)

TRUE

localizationLanguage

ISO 639-1 Alpha 2 code for Language. Example: en = English; fr = French

STRING

VARCHAR(2)

TRUE

Reply: GetFobPointsResponse

Field

Description

WSDL Data Type

SQL Data Type

Required?

FobPointArray

Array of fob Points

ARRAY

ARRAY

FALSE

errorMessage999

List of possible values for errors. Values are enumerated—See Appendix A: Error Messages for full details.

STRING

VARCHAR(256)

FALSE

             

 

FobPoint

Field

Description

WSDL Data Type

SQL Data Type

Required?

fobId

The Id of the FOB Point

STRING

VARCHAR(64)

TRUE

fobPostalCode

The Postal or Zip Code of the fob Point

STRING

VARCHAR(64)

TRUE

fobCity

The city of the FOB Point

STRING

VARCHAR(64)

TRUE

fobState

The state of the FOB Point in ISO 3166-2 format.

STRING

VARCHAR(64)

TRUE

fobCountry

The country of the FOB Point in Alpha 2 ISO3166 “CODE” format.

STRING

VARCHAR(64)

TRUE

CurrencySupportedArray

The currencies supported for the FOB Point

ARRAY

ARRAY

TRUE

ProductArray

An array of productIds associated with the FOB Point

ARRAY

ARRAY

TRUE

ProductArray

Field

Description

WSDL Data Type

SQL Data Type

Required?

productId

The product id

STRING

VARCHAR(64)

TRUE

CurrencySupportedArray

Field

Description

WSDL Data Type

SQL Data Type

Required?

currency

The currency supported for the FOB point in ISO4217 format.

STRING

VARCHAR(64)

TRUE

 

 

 

 

 

 

 

 

Function: getAvailableCharges()

This function will provide a list of charges and information on how to calculate charges. It is helpful for populating a database of charge types and designing logic to calculate charges.

Request: GetAvailableCharges

Field

Description

WSDL Data Type

SQL Data Type

Required?

wsVersion

The Standard Version of the Web Service being referenced. Values are enumerated: {1.0.0}

STRING

VARCHAR(64)

TRUE

id

The customerId or any other agreed upon Id.

STRING

VARCHAR(64)

TRUE

password

The password associated with the customerId.

STRING

VARCHAR(64)

FALSE

productId

The productId you are requesting charges for

STRING

VARCHAR(64)

FALSE

localizationCountry

ISO 3166-1 Alpha 2 code for Country Example: CA=Canada; US=United States

STRING

VARCHAR(2)

TRUE

localizationLanguage

ISO 639-1 Alpha 2 code for Language. Example: en = English; fr = French

STRING

VARCHAR(2)

TRUE

 

Reply: GetAvailableChargesResponse

Field

Description

WSDL Data Type

SQL Data Type

Required?

AvailableChargeArray

An array of charges

INT

INT

TRUE

errorMessage999

List of possible values for errors. Values are enumerated—See Appendix A: Error Messages for full details.

STRING

VARCHAR(256)

FALSE

             

 

 

 

 

 

AvailableChargeArray

Field

Description

WSDL Data Type

SQL Data Type

Required?

chargeId

A unique Id of the charge

INT

INT

TRUE

chargeName

The name of the charge

STRING

VARCHAR(64)

TRUE

chargeType

The type of charge. Values are enumerated {SETUP, RUN, ORDER}.

STRING

VARCHAR(64)

TRUE

chargeDescription

The charge description

STRING

VARCHAR(256)

TRUE

 

Function: GetConfigurationAndPricing()

This function will provide the pricing and configuration of a product.

Request: GetConfigurationAndPricingRequest

Field

Description

WSDL Data Type

SQL Data Type

Required?

wsVersion

The Standard Version of the Web Service being referenced. Values are enumerated: {1.0}

STRING

VARCHAR(64)

 

TRUE

id

The customerId or any other agreed upon Id.

STRING

VARCHAR(64)

TRUE

password

The password associated with the customerId.

STRING

VARCHAR(64)

FALSE

productId

The productId for the pricing

STRING

VARCHAR(64)

TRUE

partId

The partId

STRING

VARCHAR(64)

FALSE

currency

The unit of currency that the pricing should be returned in ISO4217 “CODE” format.

STRING

VARCHAR(64)

TRUE

fobId

The  fobId of the FOB point

STRING

 

VARCHAR(64)

TRUE

priceType

The type of pricing that should be returned. Values are enumerated: {Customer, List, Net }

STRING

VARCHAR(64)

TRUE

localizationCountry

ISO 3166-1 Alpha 2 code for Country Example: CA=Canada; US=United States

STRING

VARCHAR(2)

TRUE

localizationLanguage

ISO 639-1 Alpha 2 code for Language. Example: en = English; fr = French

STRING

VARCHAR(2)

TRUE

configurationType

The type of configuration of the product to be returned. Values are enumerated: {Blank, Decorated}

STRING

VARCHAR(32)

TRUE

 

Reply: GetConfigurationAndPricingResponse

Field

Description

WSDL Data Type

SQL Data Type

Required?

Configuration   

An object to hold Configuration data.

OBJECT

OBJECT

TRUE

ErrorMessage999

Response for any error requiring notification to requestor

OBJECT

OBJECT

FALSE

 

Configuration— An object to hold Configuration data.

Field

Description

WSDL Data Type

SQL Data Type

Required?

PartArray

An array of Parts and their pricing and configuration data

ARRAY

ARRAY

TRUE

LocationArray

An array of Locations and their pricing and configuration data

ARRAY

ARRAY

FALSE

productId

The product family. This is how the part is marketed.

STRING

VARCHAR(64)

TRUE

currency

The currency the request of the request in ISO 4217 format

STRING

VARCHAR(64)

TRUE

FobArray

An array of FOB points that support this configuration

ARRAY

ARRAY

TRUE

fobPostalCode

The postal code of the FOB point

STRING

VARCHAR(64)

FALSE

priceType

The type of price requested. Values are enumerated: {List, Net, Customer}.

STRING

VARCHAR(64)

TRUE

 

FobArray— An array of FOB points that support the configuration.  By default, this will always include the valid FOB point that was sent as part of the request. 

Field

Description

WSDL Data Type

SQL Data Type

Required?

fobId

The FOB point of the pricing

STRING ARRAY

VARCHAR(64) ARRAY

TRUE

fobPostalCode

The postal code of the FOB point

STRING

VARCHAR(64)

FALSE

 

Part—This object contains information about a part. Parts can either be the main part, required parts, or optional parts that customers can use to configure a product. The partId and partGroup combination should be unique.

Field

Description

WSDL Data Type

SQL Data Type

Required?

partId

The partId

STRING

VARCHAR(64)

TRUE

partDescription

A description of the partId

STRING

VARCHAR(128)

FALSE

PartPriceArray

An array of prices and quantities

ARRAY

ARRAY

FALSE

partGroup

A numeric identifier grouping mutually exclusive parts together. When configuring data, always start with part group “1”

NUMBER

INT

TRUE

nextPartGroup

The next mutually exclusive partGroup to complete configuration of the product

NUMBER

INT

FALSE

partGroupRequired

A boolean value specifying if this partGroup is required for the product configuration. If set to TRUE, a selection in the partGroup is required for ordering.

BOOLEAN

BOOLEAN

TRUE

partGroupDescription

A description of the partGroup. Examples: “Main Product”, “Optional Lid”, “Straw”, etc.

STRING

VARCHAR(64)

TRUE

ratio

Describes how the amount of partIds that need to be added to the order based on the number of products ordered. Example: If 8 partIds would be required per 1 product ordered, then 8 should be used as the ratio.  If one partId is required for every 8 products, than use .125

DOUBLE

DECIMAL (12,4)

TRUE

defaultPart

This part is included in the “Basic Pricing Configuration” service price. This field is optional, but highly encouraged.

BOOLEAN

BOOLEAN

FALSE

LocationIdArray

An array of LocationIDs that are available for decoration because the select part has been configured.

ARRAY

ARRAY

FALSE

 

PartPrice—This object contains pricing a product based on the partId. Prices are additive in nature. A configuration that requires three parts with three different prices should be summed together on the purchase order.

Field

Description

WSDL Data Type

SQL Data Type

Required?

minQuantity

The minimum quantity for the price break.

INT

INT

TRUE

price

The base price of the good without decoration

DOUBLE

DECIMAL (12,4)

TRUE

discountCode

The industry discount code associated with the price.

STRING

VARCHAR(1)

FALSE

priceUom

Enumerated list of unit of measure used to describe the price. Values are: {BX, CA, DZ, EA, KT, PR, PK, RL, ST, SL, TH}

BX - Box

CA - Case

DZ - Dozen

EA - Each

KT - Kit

PR - Pair

PK - Package

RL - Roll

ST - Set

SL - Sleeve

TH - Thousand

STRING

VARCHAR(2)

TRUE

priceEffectiveDate

The date the price is effective in ISO8601 format.

DATE

DATE

TRUE

priceExpiryDate

The date the price is no longer effective in ISO8601 format.

DATE

DATE

TRUE

 

 

 

Location—This object contains decoration and location details for a given part.

Field

Description

WSDL Data Type

SQL Data Type

Required?

locationId

The Id of the location

INT

INT

TRUE

locationName

The name of the location

STRING

VARCHAR(64)

TRUE

DecorationArray

An array of decorations that are valid for the given location

ARRAY

ARRAY

TRUE

decorationsIncluded

The number of decorations included in the price

INT

INT

TRUE

defaultLocation

Signifies default location for the product.

BOOLEAN

BOOLEAN

TRUE

maxDecoration

The maximum amount of decorations for this location

INT

INT

TRUE

minDecoration

The minimum amount of decorations for this location

INT

INT

TRUE

locationRank

Popularity of location based on supplier experience

INT

INT

FALSE

 

LocationIDArray—This is a list of locationIds that are valid based on the partID that was configured.

Field

Description

WSDL Data Type

SQL Data Type

Required?

locationID

The Id of the available location.

INT

INT

TRUE

 

Decoration—This object contains decoration information that are valid for a specific location

Field

Description

WSDL Data Type

SQL Data Type

Required?

­decorationId

The ID of the decoration

INT

INT

TRUE

decorationName

The name of the decoration

STRING

VARCHAR(64)

FALSE

decorationGeometry

The geometry of the decoration. Values are enumerated: {Circle, Rectangle, Other}.

STRING

VARCHAR(64)

TRUE

decorationHeight

The maximum imprint height of the decoration; leave blank if the imprint is not rectangular

DOUBLE

DECIMAL (12,4)

FALSE

decorationWidth

The maximum imprint width of the decoration; leave blank if the imprint is not rectangular

DOUBLE

DECIMAL (12,4)

FALSE

decorationDiameter

The maximum imprint diameter of the decoration; leave blank if the imprint is not circular

DOUBLE

DECIMAL (12,4)

FALSE

decorationUom

The unit of measure for the decoration area in ISO 20022

https://www.iso20022.org/standardsrepository/public/wqt/Description/mx/dico/codesets/_Y4XF0tp-Ed-ak6NoX_4Aeg_385163498

STRING

VARCHAR(64)

TRUE

allowSubForDefaultLocation

Buyer is allowed to substitute a decoration location without changing the price

BOOLEAN

BOOLEAN

TRUE

allowSubForDefaultMethod

Buyer is allowed to substitute this decoration method without changing the price

BOOLEAN

BOOLEAN

TRUE

itemPartQuantityLTM

Specifies the Part Quantity that is the absolute minimum that can be ordered with a Less Than Minimum (LTM) charge.

INT

INT

FALSE

ChargeArray

An array of setup charge data

ARRAY

ARRAY

FALSE

decorationUnitsIncluded

The number of included decoration units. For example, if 1 color decoration is included set value to “1”. If 7,500 stiches are included set value to “7500”

INT

INT

FALSE

decorationUnitsIncludedUom

Values are enumerated: {Colors, Inches, Other, Stitches, SquareInches }.

STRING

STRING

FALSE

decorationUnitsMax

This is the max number of decoration units for this decoration/location combination.

INT

INT

FALSE

defaultDecoration

Specifies whether this is the default decoration for this location

BOOLEAN

BOOLEAN

TRUE

leadTime

The leadtime for the given decoration

INT

INT

FALSE

rushLeadTime

The lead time for rush service for a given decoration (rush charges may apply)

INT

INT

FALSE

 

 

Charge—This object contains a charge that is associated with the setup of the product, location and decoration configuration.

Field

Description

WSDL Data Type

SQL Data Type

Required?

chargeId

The Id of the charge

INT

INT

TRUE

chargeName

The name of the charge

STRING

VARCHAR(64)

TRUE

chargeType

The type of charge. Values are enumerated {Order, Run, Setup}.

STRING

VARCHAR(64)

TRUE

chargeDescription

The charge description

STRING

VARCHAR(256)

TRUE

ChargePriceArray

An array of charge prices

ARRAY