Promotional Products Data Interface Specification for Web services

 

 

Invoice 1.0.0

 


 

 

Date: 10/11/2019

 

Document Change Log

Version

Date

Reason for Change

Authors

1.0.0

2020-01-27

Version 1.0.0 Release

Stephen Luisser - Essent Corporation

Peter Tu - AnyPromo

Paul Fleischman - PCNA

 

Contributors

The following have contributed to the creation of this specification:

 

Authors:

       Stephen Luisser, Vice President, Essent Corporation

       Peter Tu, President, AnyPromo

       Paul Fleischman, Technical Lead, PCNA

 

Contributors: The PromoStandards Standards Committee

 

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

 

This function will send invoices based on the criteria provided in the queryType field.

Request: GetInvoiceRequest

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 customerId or any other agreed upon Id.

64 STRING

TRUE

password

The password associated with the customerId.

64 STRING

FALSE

queryType

The type of invoice query requested

Enumerated INT

TRUE

referenceNumber

The purchase order number for queryType =1 or the invoice number for queryType = 2.

  64 STRING

FALSE

requestedDate

The date of the invoice for queryType = 3.  This field does not include a time component and it is up to the requesting party to determine if the date should be adjusted if the publishing party is on the other side of the international date line so that invoices are not missed.

DATE

FALSE

availableTimeStamp

Beginning date time since an invoice was made available in UTC.  This field must be included for queryType = 4.

DATETIME

FALSE

 

GetInvoiceRequest queryType

queryType

Short Name

Description

1

PO Number Search

Search for invoices by purchase order number

2

Invoice Number Search

Search for invoice by invoice number

3

Date Search

Search for invoices with an invoice date specified by the requestedDate

4

Available Date Time Search

Search for invoices that were made available by a date time greater than the value specified by availableTimeStamp

 

Reply: GetInvoiceResponse

Field

Description

Data Type

Required

InvoiceArray

An array of invoice objects

ARRAY

FALSE

ServiceMessageArray

An array of ServiceMessage objects

OBJECT

FALSE

 


 

 

Invoice Object

Field

Description

Data Type

Required

invoiceNumber

The invoice number

64 STRING

TRUE

invoiceType

The type of invoice; values are enumerated: “INVOICE”, “CREDIT MEMO”.  Currency amounts should be positive for type CREDIT MEMO.

64 STRING FACIT

TRUE

invoiceDate

The date the invoice was generated.  This field does not include a time component and it is up to the consuming party to determine if the data should be adjusted if the publishing party is on the other side of the international date line.

OBJECT ARRAY

TRUE

purchaseOrderNumber

The purchase order number.  Consolidated Purchase Orders are not supported by this version.

64 STRING

FALSE

purchaseOrderVersion

The version of the purchase order number as submitted by the distributor.

64 STRING

FALSE

BillTo

The Bill To Address (AccountInfo Object)

OBJECT

FALSE

SoldTo

The Sold To Address (AccountInfo Object)

OBJECT

FALSE

invoiceComments

General comments for the invoice

STRING

FALSE

paymentTerms

The terms of the invoice

64 STRING

FALSE

paymentDueDate

The Date the invoice must be paid in full without incurring late charges.

DATE

TRUE

currency

The currency of the invoice in ISO4217 format

Enumerated STRING

TRUE

fobId

The fob point of the invoice

64 STRING

FALSE

salesAmount

The amount of the sale in the currency specified.

DOUBLE

TRUE

shippingAmount

The amount of the shipping charges in the currency specified.

DOUBLE

TRUE

handlingAmount

The amount of the handling charges in the currency specified.

DOUBLE

TRUE

taxAmount

The total amount of taxes in the currency specified.

DOUBLE

TRUE

invoiceAmount

The total amount of the invoice in the currency specified.

 

Note: invoiceAmount = salesAmount + shippingAmount + handlingAmount + taxAmount

DOUBLE

TRUE

advancePaymentAmount

The amount of any advanced payments in the currency specified.  If the source system does not support including prepayments on an invoice this value should be set to zero.

DOUBLE

TRUE

invoiceAmountDue

The total of the invoice amount due after applying any prepayments in the currency specified.

 

Note: invoiceAmountDue = invoiceAmount - advancePaymentAmount

DOUBLE

TRUE

invoiceDocumentUrl

The url to be able to download the physical invoice document.

1024 STRING

FALSE

InvoiceLineItemsArray

An array of invoice line item objects

OBJECT ARRAY

TRUE

SalesOrderNumbersArray

An array of sales order numbers included in the invoice.

OBJECT ARRAY

FALSE

TaxArray

An array of tax objects.  The sum of the taxes within this array should equal the value in the taxAmount field.

OBJECT ARRAY

FALSE

invoicePaymentUrl

The url used to submit payment for the invoice

1024 STRING

FALSE

 

AccountInfo Object

Field

Description

Data Type

Required

accountName

The name of the account that will be invoiced for the purchase order.  This also represents the companyName field from the PO.

64 STRING

FALSE

accountNumber

The account number invoiced.

64 STRING

FALSE

attentionTo

Attention To (first and last name of contact)

64 STRING

FALSE

address1

Address line 1

35 STRING

FALSE

address2

Address line 2

35 STRING

FALSE

address3

Address line 3

35 STRING

FALSE

city

The city

30 STRING

FALSE

region

The 2 character US state abbreviation or 2-3 character non-US region.

3 STRING

FALSE

postalCode

The postal code

10 STRING

FALSE

country

The country in ISO 3166-2 format

2 STRING

FALSE

email

The email

128 STRING

FALSE

phone

The phone number

32 STRING

FALSE

 

InvoiceLineItem Object

Field

Description

Data Type

Required

invoiceLineItemNumber

The line item number of the line item

DOUBLE

FALSE

productId

The productId when the line item applies to a product.

64 STRING

FALSE

partId

The partId when the line item applies to a product.

64 STRING

FALSE

chargeId

The chargeId when the line item applies to a charge.

64 STRING

TRUE

purchaseOrderLineItemNumber

The line item number of the purchase order that the invoice references

64 STRING

FALSE

orderedQuantity

The quantity ordered by the referenced purchase order

DOUBLE

FALSE

invoiceQuantity

The quantity of the line item invoiced.

DOUBLE

TRUE

backOrderedQuantity

The quantity of the line item backordered.

DOUBLE

FALSE

quantityUOM

The unit of measure of the orderQuantity, invoicedQuantity, and backOrderedQuantity

2 STRING FACIT

TRUE

lineItemDescription

A textual description of the line item

1024 STRING

TRUE

unitPrice

The price of the unit in the currency of the purchase order

DOUBLE

TRUE

discountAmount

An amount of discount applied to the item.

DOUBLE

FALSE

extendedPrice

The extended price for the line item

 

Note: extendedPrice = (unitPrice * invoicedQuantity) - discountAmount

DOUBLE

TRUE

distributorProductId

The distributor’s productId for the item when the line item applies to a product.

64 STRING

FALSE

distributorPartId

The distributor’s partId for the item when the line item applies to a product.

64 STRING

FALSE

 

SalesOrderNumber Object

Field

Description

Data Type

Required

salesOrderNumber

The sales order associated with the invoice.

64 STRING

TRUE

 

Tax Object

Field

Description

Data Type

Required

taxType

The type of tax the identifier applies to. Values are enumerated: “SALES”, “HST/GST”, “PST”, “VAT”.

64 STRING FACIT

TRUE

taxJurisdiction

The jurisdiction for the tax.  For example, NJ, PA or Philadelphia City.

64 SRING

TRUE

taxAmount

The amount of tax

DOUBLE

TRUE

 

 


 

Function: getVoidedInvoices()

 

This function will send voided invoices based on the criteria provided in the queryType field.

Request: GetVoidedInvoiceRequest

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 customerId or any other agreed upon Id.

64 STRING

TRUE

password

The password associated with the customerId.

64 STRING

FALSE

queryType

The type of invoice query requested

Enumerated INT

TRUE

referenceNumber

The purchase order number for queryType =1 or the invoice number for queryType = 2.

  64 STRING

FALSE

requestedDate

The date the invoice was voided for queryType = 3.  This field does not include a time component and it is up to the requesting party to determine if the date should be adjusted if the publishing party is on the other side of the international date line so that invoices are not missed.

DATE

FALSE

availableTimeStamp

Beginning date time since a voided invoice was made available in UTC.  This field must be included for queryType = 4.

DATETIME

FALSE

 

GetInvoiceRequest queryType

queryType

Short Name

Description

1

PO Number Search

Search for voided invoices by purchase order number

2

Invoice Number Search

Search for voided invoice by invoice number

3

Date Search

Search for invoices with a voided date specified by the requestedDate

4

Available Date Time Search

Search for voided invoices that were made available by a date time greater than the value specified by availableTimeStamp

 

Reply: GetVoidedInvoiceResponse

Field

Description

Data Type

Required

VoidedInvoiceArray

An array of voided invoice objects

ARRAY

FALSE

ServiceMessageArray

An array of ServiceMessage objects

OBJECT

FALSE

 

VoidedInvoice Object

Field

Description

Data Type

Required

invoiceNumber

The invoice number

64 STRING

TRUE

voidDate

The date the invoice was voided. This field does not include a time component and it is up to the consuming party to determine if the data should be adjusted if the publishing party is on the other side of the international date line.

DATE

TRUE

Enumerated Type Restrictions

 

Field

Description

Data Type

Enumeration Values

wsVersion

The Standard Version of the Web Service being referenced

64 STRING FACIT

1.0.0

invoiceType

The type of invoice

64 STRING FACIT

INVOICE

CREDIT MEMO

quantityUOM

The unit of measure for quantity based field

2 STRING FACIT

BX (Box)

CA (Case)

DZ (Dozen)

EA (Each)

KT (Kit)

PR (Pair)

PK (Package)

RL (Roll)

ST (Set)

SL (Sleeve)

TH (Thousand)

taxType

The type of tax

64 STRING FACIT

SALES

HST/GST

PST

VAT

 


 

 

Appendix A: Service Messages

 

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

256 STRING

TRUE

severity

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

ENUMERATED 64 STRING

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

 

Service Specific Codes

These error codes are only for this service.

 

Code

Description

901

queryType not found

902

queryType not supported

903

No Invoices were found for the requested criteria

 

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 located at: 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."