Promotional Products Data Interface Specification for Web services

 

 

 

Invoice

 

 

Version: 0.0.1

Date: 2017-03-15

Document Change Log

Version

Date

Reason for Change

Author

0.0.1

3/15/2017

Initial Draft

Eric Shonebarger, CIO, Hit Promotional Products Inc

 

 

 

 

 

 

 

 

 

 

 

 

 

 

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

                           

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 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: GetInvoiceRequest

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

queryType

The type of invoice query requested

INT

INT

TRUE

referenceNumber

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

STRING

VARCHAR(64)

TRUE

invoiceRequestedDate

The date of the invoice for queryType =3.

DATE

DATE

TRUE

 

 

queryType

Short Name

Description

1

PO Search

Search for invoices by purchase order number

2

Invoice Search

Search for invoice by invoice number

3

Invoice Date Search

Search for invoices by a given invoice date

 

 

Reply: GetInvoiceResponse

 

GetInvoiceResponse

Field

Description

WSDL Data Type

SQL Data Type

Required?

InvoiceArray

An array of invoice objects

ARRAY

ARRAY

FALSE

ErrorMessage

List of possible values for errors.  Values are enumerated—See Appendix A: Error Messages for full details.

OBJECT

OBJECT

FALSE

 

 

Invoice

Field

Description

WSDL Data Type

SQL Data Type

Required?

invoiceNumber

The invoice number

STRING

VARCHAR(64)

TRUE

invoiceType

The type of invoice; values are enumerated: “INVOICE” “CREDIT MEMO”. For type “CREDIT MEMO” currency amounts should be negative.

STRING

VARCHAR(64)

TRUE

invoiceDate

The date of the invoice

DATE

DATE

TRUE

purchaseOrderNumber

The purchase order number

STRING

VARCHAR(64)

FALSE

BillTo

The Bill To Address(AccountInfo Object)

OBJECT

OBJECT

TRUE

SoldTo

The Sold To Address(AccountInfo Object)

OBJECT

OBJECT

TRUE

terms

The terms of the invoice

STRING

VARCHAR(64)

FALSE

currency

The currency of the invoice in ISO4217 format

STRING

VARCHAR(64)

TRUE

fob

The fob point of the invoice

STRING

VARCHAR(64)

FALSE

salesAmount

The amount of the sale in the currency specified.

DOUBLE

DECIMAL(12,4)

TRUE

shippingAndHandlingAmount

The amount of the shipping and handling charges in the currency specified.

DOUBLE

DECIMAL(12,4)

TRUE

totalAmount

The total amount of the invoice in the currency specified.

DOUBLE

DECIMAL(12,4)

TRUE

advancePaymentAmount

The amount of any advanced payments in the currency specified.

DOUBLE

DECIMAL(12,4)

TRUE

invoiceAmount

The total of the invoice amount in the currency specified.  Note:

salesAmount+shippingAndHandlingAmount = totalAmount

totalAmount - advancePaymentAmount = InvoiceAmount

DOUBLE

DECIMAL(12,4)

TRUE

InvoiceLineItemsArray

An array of invoice line item data

ARRAY

ARRAY

TRUE

SalesOrderNumbersArray

An array of sales order data

ARRAY

ARRAY

TRUE

 

AccountInfo

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)

FALSE

accountNumber

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

STRING

VARCHAR(64)

FALSE

AddressLinesArray

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

STRING ARRAY OF 4

VARCHAR(64)

TRUE

city

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

STRING

VARCHAR(64)

FALSE

state

The state

STRING

VARCHAR(2)

FALSE

postalCode

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

STRING

VARCHAR(64)

FALSE

 

 

 

 

 

 

 

 

InvoiceLineItems

Field

Description

WSDL Data Type

SQL Data Type

Required?

invoiceLineItemID

The ID of the lineitem

INT

INT

TRUE

invoiceLineItemNumber

The line item number of the line item

DOUBLE

DECIMAL (12,4)

FALSE

purchaseOrderLineItemNumber

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

DOUBLE

DECIMAL(12,4)

FALSE

lineItemType

The type of line item; values are enumerated: “LINE ITEM”, “TAX”

STRING

VARCHAR(64)

TRUE

orderedQuantity

The quantity ordered by the referenced purchase order

INT

INT

FALSE

invoiceQuantity

The quantity of the line item invoiced.

INT

INT

TRUE

backOrderedQuantity

The quantity of the line item backordered.

INT

INT

FALSE

quantityUOM

The unit of measure of the orderQuantity, shippedQuantity, back OrderedQuantity; values are enumerated: “EACH” “DOZENS”, “HOURS”

STRING

VARCHAR(64)

TRUE

lineItemDescription

A textual description of the line item

STRING

 VARCHAR(1024)

TRUE

unitPrice

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

DOUBLE

DECIMAL (12,4)

TRUE

extendedPrice

The unitPrice multiplied by the invoicedQuantity

DOUBLE

DECIMAL(12,4)

TRUE

lineItemTax

A Boolean set to TRUE when the line item represents a tax; Otherwise FALSE

BOOLEAN

BOOLEAN

TRUE

lineItemTaxType

The type of tax referenced on the line item. Requires lineItemTax = TRUE; values are enumerated: “SALES”, “HST/GST”, “PST”

STRING

VARCHAR(64)

FALSE

 

SalesOrderNumbers

Field

Description

WSDL Data Type

SQL Data Type

Required?

salesOrderNumber

The sales order associated with the invoice.

STRING

VARCHAR(64)

TRUE

 

 

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

901

queryType not found

902

referenceNumber not found

903

queryType not supported