Promotional Products Data Interface Specification for Web services

 

 

 

Purchase Order

****NOTE****

This is an old version, please use 1.0.0

*************

 

 

Version: 0.0.7

Date: 2017-08-22

Document Change Log

Version

Date

Reason for Change

Author

0.0.0

3/15/2017

Initial Draft

Eric Shonebarger, CIO, Hit Promotional Products Inc

0.0.1

3/27/2017

Revisions during WSDL creation

Paul Fleischman, Technical Lead, PCNA

0.0.3

5/31/2017

Revisions during alpha testing

Paul Fleischman, Technical Lead, PCNA

0.0.4

6/7/2017

Revisions during alpha testing

Paul Fleischman, Technical Lead, PCNA

0.0.5

6/27/2017

Revisions during alpha testing

Paul Fleischman, Technical Lead, PCNA

0.0.6

7/26/2017

Revisions during alpha testing

Paul Fleischman, Technical Lead, PCNA

0.0.7

8/21/2017

Revisions during beta testing

Paul Fleischman, Technical Lead, PCNA

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Contributors

The following have contributed to the creation of this specification:

Contributors:    Eric Shonebarger, CIO Hit Promotional Products, Inc

                            Jon Norris, VP of Operations Starline

                            Paul Fleischman, Technical Lead PCNA

                           

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: getSupportedPODataTypes()

Request: getSupportedPODataTypesRequest

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

 

Reply: getSupportedPODataTypesReply

Field

Description

WSDL Data Type

SQL Data Type

Required?

SupportedDataTypes

An array of supported purchase order data types for this supplier

ARRAY

ARRAY

TRUE

SupportedDataTypes[]

Field

Description

WSDL Data Type

SQL Data Type

Required?

supportedDataTypes

Signifies which purchase order datatypes the supplier supports. Values are enumerated: “Blank”, “Sample”, “Simple” “Configured”

ENUMERATED STRING

VARCHAR(32)

TRUE

 

 

 

 

Function: sendPO()

This function will send a configured purchase order to a vendor. The purchase order is designed to work in conjunction with data from the Promostandards Product Pricing and Configuration web service. More information on Product Pricing and Configuration can be found at  http://promostandards.org

 

Request: sendPORequest

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 customer Id.

STRING

VARCHAR(64)

FALSE

PO

The object containing the Purchase Order

OBJECT

OBJECT

TRUE

 

PO

Field

Description

WSDL Data Type

SQL Data Type

Required?

orderType

The type of data transferred in the request; values are enumerated:

“Blank”—This is data is for blank goods.

“Sample”—This data is for a random sample order

“Simple”—The data in the purchase order is sent over without supplier configured data and will be processed manually.

“Configured”—The data is sent over in conjunction with the supplier’s Product Pricing and Configuration web service and designed for electronic processing of the purchase order.

ENUMERATED STRING

VARCHAR(64)

TRUE

orderNumber

Purchase order number

STRING

VARCHAR(64)

TRUE

orderDate

The date and time of the purchase order.

DATE

DATE

TRUE

lastModified

The date and time the purchase order was last modified

DATE

DATE

FALSE

orderVersion

The version of the purchase order

STRING

VARCHAR(64)

TRUE

totalAmount

The total dollar amount of the purchase order

DOUBLE

DECIMAL(12,4)

TRUE

paymentTerms

The terms of the purchase order.  i.e. NET15, NET30, etc.

STRING

STRING

FALSE

rush

Used to indicate a rush on the purchase order.  Use the number of production days to signify the rush.  Example: 1-day rush, place a “1” in the field.

INT

INT

FALSE

currency

The currency the purchase order is transacted in ISO4217 format.

STRING

VARCHAR(64)

TRUE

DigitalProof

An object containing preproduction digital proof information

OBJECT

OBJECT

FALSE

OrderContactArray

An array of contact information in regards to this order.

ARRAY

ARRAY

FALSE

ShipmentArray

Any array of purchase order shipment objects

ARRAY

ARRAY

TRUE

LineItemArray

An array of line items of the purchase order

ARRAY

ARRAY

TRUE

termsAndConditions

The terms and conditions for this purchase order.  Information that is order specific or information dealing with the configuration or shipment of the order should not be entered here.

STRING

VARCHAR(MAX)

TRUE

salesChannel

The sales channel

STRING

VARCHAR(64)

FALSE

promoCode

The promotion code

STRING

VARCHAR(64)

FALSE

discountMethod

The discount method

STRING

VARCHAR(64)

FALSE

discountType

The discount type

STRING

VARCHAR(64)

FALSE

TaxInformationArray

An array of TaxInformation objects related to calculating taxes

ARRAY

ARRAY

FALSE

 

DigitalProof

Field

Description

WSDL Data Type

SQL Data Type

Required?

required

A Boolean value set to TRUE indicates a proof is required for this purchase order; the value is FALSE otherwise.

BOOLEAN

BOOLEAN

TRUE

DigitalProofAddressesArray

An array containing DigitalProofAddress objects.

ARRAY

ARRAY

TRUE

 

DigitalProofAddress

Field

Description

WSDL Data Type

SQL Data Type

Required?

type

The type of address of the digital proof.  Values are enumerated: Email, Webservice

STRING

VARCHAR(64)

TRUE

email

The address that the digital proof should be sent to prior to production.

STRING

VARCHAR(128)

TRUE

lineItemGroupingId

What line item group does this proof address link to

INT

INT

TRUE

 

TaxInformation

Field

Description

WSDL Data Type

SQL Data Type

Required?

taxId

The purchasers tax identifier

STRING

VARCHAR(64)

TRUE

taxType

The type of tax the identifier applies to. Values are enumerated: “Hst-Gst”, “Pst”, “SalesTax”

ENUMERATED STRING

VARCHAR(64)

TRUE

taxExempt

Tax Except

BOOLEAN

BOOLEAN

TRUE

taxJurisdiction

Tax Jurisdictions

UNBOUNDED STRING ARRAY

VARCHAR(64)

TRUE

 

LineItem

Field

Description

WSDL Data Type

SQL Data Type

Required?

lineNumber

The line number of the line item

STRING

VARCHAR(64)

TRUE

description

The description of the line item.  For simple order type (not using a configuration), use this field to explain the details.

STRING

VARCHAR(MAX)

TRUE

lineType

The type of order; values are enumerated:

·   “New” –A new purchase order with no prior order reference

·   “Repeat” —An exact repeat of a previous purchase order with the vendor

·   “Reference” –An order that has the same artwork as a previous order.

ENUMERATED STRING

VARCHAR(64)

TRUE

Quantity

The quantity object that contains the value and unit of measure

OBJECT

OBJECT

TRUE

fobId

Used to indicate the FOB point.  Use fobId from the supplier’s Product Pricing and Configuration Service to populate this information.

STRING

VARCHAR(64)

FALSE

ToleranceDetails

The object containing how tolerant this line is to overrun and underruns.

OBJECT

OBJECT

TRUE

allowPartialShipments

Allow partial shipments of this line item

BOOLEAN

BOOLEAN

TRUE

unitPrice

The unit price of the line item

DOUBLE

DECIMAL(12,4)

TRUE

extendedPrice

The total price of the line item (unit price * quantity)

DOUBLE

DECIMAL(12,4)

TRUE

requestedShipDate

The date the line item is requested to ship from the FOB point.

DATE

DATE

FALSE

requestedInHands

The date the line item is requested to arrive at the shipping destination

DATE

DATE

FALSE

referenceSalesQuote

The sales quote number associated with this purchase order line (if applicable).

VARCHAR(64)

VARCHAR(64)

FALSE

Program

Program pricing information.

OBJECT

OBJECT

FALSE

endCustomerSalesOrder

The distributor’s order number provided to the end customer

VARCHAR(64)

VARCHAR(64)

FALSE

productId

The manufacturer’s product id associated with the configuration data.

STRING

VARCHAR(64)

FALSE

customerProductId

The distributor’s product id

STRING

VARCHAR(64)

FALSE

lineItemGroupingId

An identifier that allows configuration data to be spread out among multiple purchase order lines.  Keep lineItemGroupingID unique when referencing the same product on the purchase order.  Any change to the product, location, decoration, or artwork should produce a unique lineItemGroupingID to the purchase order.

STRING

VARCHAR(64)

FALSE

PartArray

An array of product part information.  This array should be populated with information from the supplier’s PromoStandards Product Pricing and Configuration service

ARRAY

ARRAY

FALSE

Configuration

An object containing line item configuration data

OBJECT

OBJECT

FALSE

           

 

ToleranceDetails

tolerance

An enumerator specifying the quantity tolerance allowed:  AllowOverRun, AllowUnderrun, ExactOnly.  Specifying AllowOverRun or AllowUnderrun without a value and uom will result in the supplier’s discretion. 

ENUMERATED STRING

VARCHAR(64)

TRUE

value

The overrun/underrun permitted.  This element is ignored if ExactOnly is specified for tolerance.

DECIMAL

DECIMAL(12,4)

FALSE

uom

The unit of measure for value element; enumerated values are: {Percent, Quantity}.  This element is ignored if ExactOnly is specified for tolerance.

 

ENUMERATED STRING

VARCHAR(10)

FALSE

 

Program

id

The program id associated with this purchase order line (if applicable).

VARCHAR(64)

VARCHAR(64)

FALSE

name

The program name associated with this purchase order line (if applicable).

VARCHAR(64)

VARCHAR(64)

FALSE

 

Quantity

value

The quantity value

DECIMAL

DECIMAL(12,4)

TRUE

uom

The unit of measure; values are enumerated.

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

 

ENUMERATED STRING

VARCHAR(2)

TRUE

 

Configuration

Field

Description

WSDL Data Type

SQL Data Type

Required?

referenceNumber

The previous order number that this purchase order is referencing

STRING

VARCHAR(64)

FALSE

referenceNumberType

The type of the prior order reference; values are enumerated: “PurchaseOrder”,”SalesOrder”, “JobOrWorkOrder”

ENUMERATED STRING

VARCHAR(64)

FALSE

preProductionProof

Indicates that this line item is for a pre-production proof

BOOLEAN

BOOLEAN

TRUE

ChargeArray

An array of charge information.  This array should be populated with information from the supplier’s PromoStandards Product Pricing and Configuration service

ARRAY

ARRAY

FALSE

LocationArray

An array of Decoration Location Information.  This array should be populated with information from the supplier’s PromoStandards Product Pricing and Configuration service

ARRAY

ARRAY

TRUE

 

Part

Field

Description

WSDL Data Type

SQL Data Type

Required?

partGroup

 

STRING

VARCHAR(64)

TRUE

partId

The part Id from the supplier’s PromoStandards Product Pricing and Configuration service

STRING

VARCHAR(64)

TRUE

customerPartId

 

STRING

VARCHAR(64)

FALSE

description

The description from the supplier’s PromoStandards Product Pricing and Configuration service.

STRING

VARCHAR(4000)

FALSE

Quantity

The quantity object that contains the value and unit of measure

OBJECT

OBJECT

TRUE

locationLinkId

An array of location link Ids.  This links the part to its configured locations.

ARRAY OF INTEGERS

INT[]

FALSE

unitPrice

The price of the part being referenced.

DECIMAL

DECIMAL(12,4)

FALSE

extendedPrice

The unitPrice multiplied by the Quantity value.

DECIMAL

DECIMAL(12,4)

FALSE

ShipmentLinkArray

Link this part and a specified quantity to one or many shipments.

OBJECT

OBJECT

FALSE

 

ShipmentLink   

Field

Description

WSDL Data Type

SQL Data Type

Required?

shipmentId

The shipment Id

STRING

VARCHAR(64)

TRUE

Quantity

The quantity object that contains the value and unit of measure

OBJECT

OBJECT

TRUE

 

Charge

Field

Description

WSDL Data Type

SQL Data Type

Required?

chargeId

The chargeId from the supplier’s PromoStandards Product Pricing and Configuration service

STRING

VARCHAR(64)

TRUE

chargeName

The chargeName from the supplier’s PromoStandards Product Pricing and Configuration service.

STRING

VARCHAR(128)

FALSE

description

The charge description from the supplier’s PromoStandards Product Pricing and Configuration service.

STRING

VARCHAR(4000)

FALSE

chargeType

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

ENUMERATED STRING

VARCHAR(64)

TRUE

Quantity

The quantity object that contains the value and unit of measure

OBJECT

OBJECT

TRUE

unitprice

The price of the charge being referenced.

DECIMAL

DECIMAL(12,4)

FALSE

extendedPrice

The unitPrice multiplied by the Quantity value

DECIMAL

DECIMAL(12,4)

FALSE

 

Location

Field

Description

WSDL Data Type

SQL Data Type

Required?

locationLinkId

An identifier to be used within the Part Array to link configured locations to a part.  Due to different colors and sizes, identical locations may need to be decorated differently.

INT

INT

TRUE

locationId

The locationId from the supplier’s PromoStandards Product Pricing and Configuration service

INT

INT

TRUE

locationName

The locationName from the supplier’s PromoStandards Product Pricing and Configuration service.

STRING

VARCHAR(128)

FALSE

DecorationArray

An array of product decoration information

ARRAY

ARRAY

TRUE

 

Decoration

Field

Description

WSDL Data Type

SQL Data Type

Required?

decorationId

The decorationId from the supplier’s PromoStandards Product Pricing and Configuration service

INT

INT

TRUE

decorationName

The decorationName from the supplier’s PromoStandards Product Pricing and Configuration service.

STRING

VARCHAR(128)

FALSE

Artwork

The object containing the details of the artwork

OBJECT

OBJECT

TRUE

Artwork

refArtworkId

A pre-shared artwork Id that can be used by the supplier to find and reference the artwork.

STRING

VARCHAR(64)

FALSE

description

A textual description of the artwork being provided.

STRING

VARCHAR(4000)

FALSE

Dimensions

The dimensions of the artwork

OBJECT

OBJECT

FALSE

fileName

The file name and extension only of the artwork

STRING

VARCHAR(64)

FALSE

fileLocation

The exact path/location to the artwork

STRING

VARCHAR(1024)

FALSE

transportMechanism

The mechanism that will be used to transport the artwork; values are enumerated: “Email”, “Url”, “Ftp”, “ArtworkToFollow”

ENUMERATED STRING

VARCHAR(64)

FALSE

instructions

Any instructions regarding the processing or modification of artwork.  Adding instructions will cause delays in processing.

STRING

VARCHAR(MAX)

FALSE

Layers

An object that explains how the artwork layers or stops will be handled

OBJECT

OBJECT

FALSE

TypesetArray

An array of typeset data

ARRAY

ARRAY

FALSE

 

Dimensions

Field

Description

WSDL Data Type

SQL Data Type

Required?

geometry

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

ENUMERATED STRING

VARCHAR(64)

TRUE

useMaxLocationDimensions

Use the maximum allowed imprint dimensions for this location.  If this is set to true, all other dimension information is ignored except for geometry.  Note: Max dimensions be also found from the supplier’s PromoStandards Product Pricing and Configuration service.

BOOLEAN

BOOLEAN

TRUE

height

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

DECIMAL

DECIMAL (12,4)

FALSE

width

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

DECIMAL

DECIMAL (12,4)

FALSE

diameter

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

DECIMAL

DECIMAL (12,4)

FALSE

uom

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

ENUMERATED STRING

VARCHAR(64)

FALSE

 

Layers

Field

Description

WSDL Data Type

SQL Data Type

Required?

colorSystem

The color system to use

STRING

VARCHAR(64)

TRUE

LayerOrStopArray

An array of layers for the artwork

OBJECT

OBJECT

TRUE

 

LayerOrStop

Field

Description

WSDL Data Type

SQL Data Type

Required?

nameOrNumber

The name or number of the layer/stop

STRING

VARCHAR(64)

TRUE

description

A human readable description of the layer

STRING

VARCHAR(4000)

TRUE

color

The color value that corresponds to the colorSystem defined

STRING

VARCHAR(64)

TRUE

 

Typeset

Field

Description

WSDL Data Type

SQL Data Type

Required?

sequenceNumber

The order of the typeset information

INT

INT

TRUE

value

The typeset to be used on the order

STRING

VARCHAR(1024)

TRUE

font

The font to use for the typeset

STRING

VARCHAR(64)

FALSE

fontSize

The font size to use for the typeset

INT

INT

FALSE

 

Shipments

Field

Description

WSDL Data Type

SQL Data Type

Required?

ShipTo

The object containing the ship to information

OBJECT

OBJECT

TRUE

ThirdPartyAccount

The object containing the third party information

OBJECT

OBJECT

FALSE

shipReferences

Array of two strings max

STRING

VARCHAR(64)

FALSE

packingListRequired

Packing list required

BOOLEAN

BOOLEAN

TRUE

blindShip

Require blind shipping

BOOLEAN

BOOLEAN

TRUE

allowConsolidation

Allow consolidation of shipments

BOOLEAN

BOOLEAN

TRUE

FreightDetails

The details on the freight: carrier and service

OBJECT

OBJECT

TRUE

comments

Comments regarding the shipment for further clarification.  Note: Use comments only when absolutely necessary, as it may cause delays in order processing.

STRING

VARCHAR(MAX)

FALSE

 

FreightDetails

Field

Description

WSDL Data Type

SQL Data Type

Required?

carrier

The carrier name of the shipping vendor being requested.  (i.e. “UPS”, “FEDEX”, etc.)

STRING

VARCHAR(64)

TRUE

service

The service code of the shipping vendor for the service being requested.  i.e. GROUND, 2DAY, NEXTDAY, etc.

STRING

VARCHAR(64)

FALSE

 

ShipTo

Field

Description

WSDL Data Type

SQL Data Type

Required?

shipmentId

The shipment id that can be referenced in the ShipmentLink object.

STRING

VARCHAR(64)

TRUE

ContactDetails

The object containing the third party contact details

OBJECT

OBJECT

TRUE

 

ThirdPartyAccount

Field

Description

WSDL Data Type

SQL Data Type

Required?

accountName

The name of the account that will be invoiced for the purchase order.

STRING

VARCHAR(64)

TRUE

accountNumber

The number of the account that will be invoiced for the purchase order.

STRING

VARCHAR(64)

TRUE

ContactDetails

The object containing the third party contact details

OBJECT

OBJECT

TRUE

 

Contact

contactType

The type of contact.  Values are enumerated: {“Art”, “Bill”, “Expeditor”, “Order”, “Sales”, “Ship”, “Sold”}

ENUMERATED STRING

VARCHAR(64)

TRUE

ContactDetails

The object that contains the details about the contact.

OBJECT

OBJECT

TRUE

accountName

The name of the account that will be invoiced for the purchase order.

STRING

VARCHAR(64)

FALSE

accountNumber

The number of the account that will be invoiced for the purchase order.

STRING

VARCHAR(64)

FALSE

 

ContactDetails

attentionTo

Attention To (first and last name of contact)

STRING

VARCHAR(128)

FALSE

addressLines

An array of four string of length 64 to hold the address lines.

STRING ARRAY OF 4

VARCHAR(64)

FALSE

city

The city

STRING

VARCHAR(64)

FALSE

state

The state

STRING

VARCHAR(2)

FALSE

country

The country in ISO 3166-2 format

STRING

VARCHAR(2)

FALSE

postalCode

The postal code

STRING

VARCHAR(64)

FALSE

email

The Email

STRING

VARCHAR(128)

FALSE

phone

The phone number

STRING

VARCHAR(64)

FALSE

comments

Comments regarding the contact for further clarification.  Note: Use comments only when absolutely necessary, as it may cause delays in order processing.

STRING

VARCHAR(MAX)

FALSE

 

Reply: SendPOResponse

Field

Description

WSDL Data Type

SQL Data Type

Required?

transactionId

The transaction identifier in response indicating a successful transfer of a schematically valid PO payload.  It can also be used for IT departments to help with diagnostics and technical support.  This transaction identifier does not indicate that the PO was successfully entered and inventory was allocated.  The use of the Order Status service can provide the status of the order going forward.  If no transaction identifier is returned, a populated ErrorMessage object must be returned indicating the fault (Error severity is a failure).  A populated ErrorMessage object returned with a transaction identifier indicates the PO was successfully transferred but initial validation detected problems preventing it from being processed without human intervention (Error severity is a warning).  Based on the agreement with the supplier, either correct these issues and resubmit a revised PO or wait for contact from a supplier representative. 

STRING

VARCHAR(MAX)

FALSE

ErrorMessageArray

An array of ErrorMessage objects.

OBJECT

OBJECT

FALSE

 

Appendix A: Error Messages

ErrorMessage

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

severity

The severity of the error.  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

Type

Description

100

Error

ID (customerID) not found

104

Error

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

105

Error

Authentication Credentials failed

110

Error

Authentication Credentials required

115

Error

wsVersion not found

120

Error

The following field(s) are required [Comma Delimited field names]

125

Error

Not Supported: [details]

999

Error

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

 

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

Severity

Description

Information

This indicates something was handled automatically or the receiver wants to communicate further details with the submitter.

Warning

This indicates a soft stop and the transaction will complete.  A warning may indicate problems that will delay the transaction.  A transaction id will be returned, thus the receiver is committed to handling the message.

Error

This indicates a hard stop and the transaction did not complete.  No transaction id will be returned, thus the receiver is not committed to handling the message and it will need to be resubmitted.

 

 

Code

Severity

Description

200

Error

Duplicated transaction detected.  PO was not submitted.

210

Error

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)

220

Error

Field is not supported: {0}

230

Warning

Field is partially supported: {0}

 

(Use in situations where a supplier cannot accommodate different line level in-hands dates, fobs, etc.  The responder will explain in the message what the course of action will be.) 

240

Error

The following is not supported by the Simple order type: {0}

250

Warning

The PO is received but there may be a delay in processing. 

260

Error

Fob id {0} specified for product {1} on line {2} is not valid.

261

Information

Fob id {0} was automatically assigned for product {1} on line {2} because none was specified.

262

Error

No Fob id is specified for line {0}

263

Warning

The receiver was unable to validate Fob id {0} specified for product {1} on line {2}.