Promotional Products Data Interface Specification for Web services

  

 

Media Content Standards

Version: 1.1.0

Date: 2017-07-18

 

 

 

Document Change Log

Version

Date

Reason for Change

Author

1.1.0

2017-07-18

Resolves the reported validation issue where Location and Decoration array require at least one element when these arrays should be optional.

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/

 

 

Media Content

Summary: Provides a mechanism to get a media content by specific parameters like (last change date, product id, part id, media type, etc).  This allows the consumer of the service to obtain specific media content for their needs.

Function: getMediaContent()

Request:

GetMediaContentRequest

Field

Description

Data Type

Required?

wsVersion

The Standard Version of the Web Service being referenced

64 STRING

YES

id

The customer Id or any other agreed upon Id.

64 STRING

YES

password

The password associated with the Id

64 STRING

NO

cultureName

The language culture name.  This tailors the response to a specific culture. i.e. language, units of measure, etc. Null assumes en-US.

ISO 639x

NO

mediaType

The type of media to return

STRING FACET

YES

productId

The product Id

64 STRING

YES

partId

The part Id associated to the product Id

64 STRING

NO

classType

Classification of the media.  See below for details on valid values.

INT

NO

  

Reply:

GetMediaContentDetailsResponse

Field

Description

Data Type

Required?

MediaContentArray

An array of media content objects

OBJECT ARRAY

NO

ErrorMessage

Response for any error requiring notification to requestor

OBJECT

NO

 

 

MediaContent Object

Field

Description

Data Type

Required?

productId

The associated Product Id

64 STRING

YES

partId

The part Id associated to the product Id.

64 STRING

NO

url

The URL of the media location.  Any valid URL can be returned including prefixes like http and ftp.

1024 STRING

YES

mediaType

The type of media

STRING FACET

YES

ClassTypeArray

An array of ClassType objects that classify of the media

OBJECT ARRAY

YES

fileSize

The file size

DOUBLE

NO

width

Width

INT

NO

height

Height

INT

NO

dpi

Dots per inch

INT

NO

color

The color description

256 STRING

NO

DecorationArray

An array of decoration objects that describe the decorations associated with the media

OBJECT ARRAY

NO

LocationArray

An array of location objects that describe the locations associated with the media

OBJECT ARRAY

NO

description

Information about the media

1024 STRING

NO

singlePart

Identifies whether the partId one to one corresponds with the image.  (Use FALSE for group shots)

BOOLEAN

YES

changeTimeStamp

The date time since last change in UTC

ISO 8601

NO

ClassType Object (See below for details on valid values)

classType

The classification of the media

INT

YES

className

The classification short name

64 STRING

YES

Decoration Object

Field

Description

Data Type

Required?

decorationId

The decoration id associated with the media

INT

YES

decorationName

The name of the decoration associated with the id

64 STRING

YES

Location Object

Field

Description

Data Type

Required?

locationId

The location id associated with the media

INT

YES

locationName

The name of the location associated with the id

64 STRING

YES

 

 

Media Date Modified

Summary: Provides a mechanism to get all product and/or part ids, of media, that changed since a specified date.

Function: getMediaDateModified()

Request:

GetMediaDateModifiedRequest

Field

Description

Data Type

Required?

wsVersion

The Standard Version of the Web Service being referenced

64 STRING

YES

id

The customer Id or any other agreed upon Id

64 STRING

YES

password

The password associated with the Id

64 STRING

NO

cultureName

The language culture name.  This tailors the response to a specific culture. i.e. language, units of measure, etc. Null assumes en-US.

ISO 639x

NO

changeTimeStamp4

Beginning date time since last change in UTC

ISO 8601

NO

  

Reply:

GetMediaDateModifiedResponse

Field

Description

Data Type

Required?

MediaDateModifiedArray

An array of MediaDateModified objects

OBJECT ARRAY

NO

ErrorMessage999

Response for any error requiring notification to requestor

OBJECT

NO

MediaDateModified Object

Field

Description

Data Type

Required?

productId

The associated Product Id

64 STRING

YES

partId

The part Id associated to the product Id

64 STRING

NO

 

 

Enumerated Type Restrictions

mediaType

The basic media type

Image - Returns images
Video - Returns videos
Audio - Returns audios
Document - Returns documents

Valid values for class type and class name:

classType

Class Name

Description

0-499

Reserved

Reserved for future use

500-999

Custom

Custom class types for implementation specific use.  These identifiers

1000

Unspecified

Unknown or unspecified shot.  This value means the shot type is unavailable for the media type.

1001

Blank

The shot is of blank media

1002

Decorated

The shot is of decorated media

1003

Alternate

The shot is alternate.  This may indicate the product is combined with other media to stage a scene.

1004

Swatch

The shot is of a swatch

1005

Custom

The shot is custom which does not fall into any specific type

1006

Primary

The primary image

1007

Front

Front view

1008

Rear

Rear view

1009

Right

Right view

1010

Left

Left view

1011

Top

Top view

1012

Bottom

Bottom view

1013

Inside

Inside view

1014

Outside

Outside view

2000

Standard

Standard Definition

2001

High

High definition

3000

Podcast

Podcast

4000

Specs

Specification sheets

4001

ProductSafety

Product safety information

4002

Facts

Fact sheets

4003

Compliance

Compliance documents

4004

ArtTemplate

Art templates

4005

Marketing

Marketing material

ErrorMessage Object

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]

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

155

Invalid Date Format

160

No Results Found

999

General Error – Contact the System Service Provider

 

 

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. 

http://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: “Media Content 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”