Promotional Products Data Interface Specification for Web services

 

 

 

 

 

 

 

Order Shipment Notification (OSN)

 

 

 

 

 

 

 

 

 

 

 

 

Version:               1.0.0

Date:                    2016-03-02

 

Document Change Log

Version

Date

Reason for Change

Author

0.0.1

2015-10-30

Initial Draft

Stephen Luisser, VP of Research Essent Corporation

0.0.2

2015-11-24

Changed shipmentDestinationType to optional.

Stephen Luisser, VP of Research Essent Corporation

0.0.3

2015-12-17

1.       Changed "ShipmentLocations" to "ShipmentLocation". 

2.       Changed ErrorMessage to an object and added object definition. 

3.       Marked SalesOrderNumberArray as optional for when writing an ErrorMessage object. 

4.       Changed version to a subversion until published.

5.       Changed “PurchaseOrderNumber “ to “purchaseOrderNumber”.

6.       Made all non-customizable enums strings.Created an

7.       Address object and referenced for ShipFrom and ShipTo.

Paul Fleischman
Technical Lead, PCNA

0.0.4

2016-01-05

1.       Consistency corrections

2.       Added Standardized Codes for ErrorMessage object

3.       Added supplierProductId, supplierPartId, distributorProductId, distributorPartId to Item array

Paul Fleischman
Technical Lead, PCNA

0.0.5

2016-01-28

1.       Removed 4th enumeration from Request.xsd file for query type

2.       Added numerical values to documentation for query type parameters

Jon Norris

VP of Operations, Starline

0.0.6

2016-01-28

1.       Capitalized the Reply name “GetOrderShipmentNotificationResponse”

2.       Created “OrderShipmentNotificationArray”: This is necessary to handle the ShipDateSearch queryType, as more than one PO will be returned at once.

3.       Moved error message out into “GetOrderShipmentNotificationResponse”

Jon Norris

VP of Operations, Starline

0.0.7

2016-01-29

Renamed “SalesOrderNumberArray” to “SalesOrderArray”

Paul Fleischman
Technical Lead, PCNA

0.0.8

2016-03-01

Added error codes range 300-399 that are specific to this service.

Jon Norris

VP of Operations, Starline

1.0.0

2016-03-02

Service moved into Prodcution

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

 


 

Order Shipment Notification

Summary: Provides a mechanism to get shipment details by specific parameters like (purchase order number, sales order number, or shipment date).  This allows the consumer of the service to obtain shipment information grouped by purchase order number and sales order number for their needs.

Function: getOrderShipmentNotification()

Request:

GetOrderShipmentNotificationRequest

 

Field

Description

Data Type

Required?

wsVersion

The Standard Version of the Web Service being referenced.

64 STRING: Enumerated

TRUE

id

The customerID or any other agreed upon ID.

64 STRING

TRUE

password

The password associated with the customerID or agreed upon ID.

64 STRING

FALSE

queryType

The type of query you wish to perform.1

String Enumerated

TRUE

referenceNumber

The purchase order or sales order number.  Required when the queryType is 1 or 2.2

64 STRING

FALSE

shipmentDateTimeStamp

The earliest date for of shipments to return in UTC 3.  Required when the queryType is 3.  ISO 8601

DATE

FALSE

 

1This indicates the type of query you are trying to perform. Valid Options:

queryType

Name

Description

1

POSearch

Query based on customer provided purchase order number.

2

SOSearch

Query based on vendor assigned sales order number.

3

ShipDateSearch

Query based on all shipments with a shipment date greater than the value specified in shipmentDateTimeStamp.

2When they queryType is (PO Search), this value represents the customer provided purchase order number.  When the queryType is (SO Search), this value represents the vendor assigned sales order number.  When the queryType is (Shipment Date Search), this value is not used and should not be passed.

3This field will indicate the date time for any shipment GREATER the shipment date time stamp provided. Note: Make sure to account for some jitter between the two systems and make sure to specify your time request in UTC and not in the local time zone.

 

 

Reply:

GetOrderShipmentNotificationResponse

 

Field

Description

Data Type

Required?

OrderShipmentNotificationArray10

An array of Order Shipment Notifications

ARRAY

FALSE

ErrorMessage999

Response for any error requiring notification to requestor

OBJECT

FALSE

 

10OrderShipmentNotificationArray

 

Field

Description

Data Type

Required?

purchaseOrderNumber

The associated purchase order.

64 STRING

TRUE

complete

All shipments for this purchase order are complete.

BOOLEAN

TRUE

SalesOrderArray

An array of sales orders associated with the purchase order.4

ARRAY

FALSE

 

4SalesOrder

Field

Description

Data Type

Required?

salesOrderNumber

The associated sales order.

64 STRING

TRUE

complete

All shipments for this sales order are complete.

BOOLEAN

TRUE

ShipmentLocationArray

An array of shipment locations.5

ARRAY

TRUE

 

5ShipmentLocation

Field

Description

Data Type

Required?

id

The id of the location.

NUMBER

FALSE

complete

All shipments for this location are complete.

BOOLEAN

TRUE

shipFromAddress

Ship-From address6

OBJECT

TRUE

shipToAddress

Ship-To address6

OBJECT

TRUE

shipmentDestinationType

Used to identify the type of destination for the Ship-To address.

64 STRING: Enumerated

FALSE

PackageArray

An array of shipment packages.7

ARRAY

FALSE

 

6Address

address1

Address Line 1

64 STRING

TRUE

address2

Address Line 2

64 STRING

FALSE

address3

Address Line 3

64 STRING

FALSE

address4

Address Line 4

64 STRING

FALSE

city

Address City

64 STRING

TRUE

region

Address Region

2 STRING

TRUE

postalCode

Address Postal Code

10 STRING

TRUE

country

Address Country

128 STRING

FALSE

 

7Package

Field

Description

Data Type

Required?

id

The id of the package

NUMBER

FALSE

trackingNumber

The tracking number for the package

128 STRING

TRUE

shipmentDate

The date for the shipment in UTC.8  ISO 8601

DATE

TRUE

dimUOM

The dimensional unit of measure

64 STRING: Enumerated

FALSE

length

The length of the package

NUMBER

FALSE

width

The width of the package

NUMBER

FALSE

height

The height of the package

NUMBER

FALSE

weightUOM

The weight unit of measure

64 STRING: Enumerated

FALSE

weight

The weight of the package

NUMBER

FALSE

carrier

The carrier delivering the package

128 STRING

FALSE

shipmentMethod

The method used for shipping (Ground)

128 STRING

FALSE

shippingAccount

The shipping account used for this shipment

128 STRING

FALSE

shipmentTerms

The terms of the shipment

128 STRING

FALSE

ItemArray

A list of items and quantities contained in the package9

ARRAY

FALSE

 

8Make sure to account for some jitter between the two systems and make sure to process the returned value as UTC and not in the local time zone.

 

9Item

Field

Description

Data Type

Required?

supplierProductId

The supplier product Id

64 STRING

FALSE

supplierPartId

The supplier part Id associated to the supplier product Id

64 STRING

FALSE

distributorProductId

The distributor product Id

64 STRING

FALSE

distributorPartId

The distributor part Id associated to the supplier product Id

64 STRING

FALSE

purchaseOrderLineNumber

The line number of the item on the purchase order.

INTEGER

FALSE

quantity

The quantity of the item.

NUMBER

FALSE

 

 

 

999ErrorMessage

Field

Description

Data Type

Required?

code

The numerical value of the code

NUMBER

YES

description

Response for any error requiring notification to requestor

256 STRING

YES

 

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

 Service Specific Code: These error codes are only for the Order Ship Notification Service

Code

Description

300

queryType not found

301

referenceNumber not found

302

shipmentDateTimeStamp is incorrect or is an invalid date range

 

Enumerated Type Restrictions

 

Field

Description

Data Type

Values

wsVersion

The Standard Version of the Web Service being referenced

64 STRING: Enumerated

1.0.0

 

shipmentDestinationType

Used to identify the type of destination for the Ship-To address.

64 STRING: Enumerated

Commercial

Residential

None

dimUOM

The dimensional unit of measure

64 STRING: Enumerated

Inches

Feet

mm

cm

Meters

weightUOM

The weight unit of measure

64 STRING: Enumerated

Ounces

Pounds

Grams

KG

 

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

Code Samples

To be published under separate specification: “Order Shipment Notification Standards Use Examples”.

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