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

ARRAY

TRUE

chargeAppliesLTM

This charge is applied with ordering Less than Minimum (LTM).

BOOLEAN

BOOLEAN

TRUE

chargesPerLocation

The number of times a charge will occur per location

INT

INT

FALSE

chargesPerColor

The number of times a charge will occur per color

INT

INT

FALSE

 

ChargePrice—This object contains a single line of a price grid represented by an X and Y axis.

Field

Description

WSDL Data Type

SQL Data Type

Required?

xMinQty

The minimum x-value quantity for this price

INT

INT

TRUE

xUom

The unit of measure for the x-axis. Values are enumerated: {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

yMinQty

The minimum y-value quantity for this price

INT

INT

TRUE

yUom

The unit of measure for the y-axis. Values are enumerated: {Colors, Inches, Other, Stitches, SquareInches }.

STRING

STRING

TRUE

price

The price of the charge

DOUBLE

DECIMAL (12,4)

TRUE

discountCode

The discount code associated with the price.

STRING

VARCHAR(1)

FALSE

repeatPrice

The price of the charge if it is a repeat order

NUMBER

DECIMAL (12,4)

FALSE

repeatDiscountCode

The discount code of the repeat price

STRING

VARCHAR(1)

FALSE

priceEffectiveDate

The date the price is effective in ISO8601 format.

DATE

DATE

FALSE

priceExpiryDate

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

DATE

DATE

FALSE

 

                                               

 

 

Appendix A: Error Messages

999ErrorMessage

Field

Description

WSDL Data Type

SQL Data Type

Required?

code

The numerical value of the code

INT

INT

TRUE

description

Response for any error requiring notification to requestor

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]

999

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

 

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

Code

Description

400

productID not found

401

currencyID not found

402

priceType not found

403

fobId not found

404

localizationCountry not found

405

localizationLanguage not found

406

configurationType not found