speedfreight web service developer guide updated november ... › wp-content › uploads › ... ·...

Speedfreight Web Service Developer’s Guide

Updated November 24, 2014

Speedfreight Web Service 2

Table of Contents

Welcome to the Worldwide Express Speedfreight Web Service ........................................... 3

Required Steps for Integrating Worldwide Express Web Services ...................................... 4

Development and Test Environment ................................................................................................ 5

How to Obtain an Authentication Key .............................................................................................. 7

Web Services Definition Language (WSDL) ................................................................................... 9

Getting Technical Support ................................................................................................................... 10

Overview of Services .............................................................................................................................. 11

Get Quote Request ................................................................................................................................... 12

Book Shipment Request ........................................................................................................................ 16

Void Shipment Request ......................................................................................................................... 20

PRO Number Request ............................................................................................................................ 21


Welcome to the Worldwide Express Speedfreight Web Service

Welcome to the Worldwide Express Speedfreight Web Service. The web service allows Worldwide Express customers the opportunity to integrate a number of LTL freight operations into their application(s). The web service provides LTL freight quotes, books and schedules shipments, generates Bills of Lading, retrieves PRO numbers, and voids shipments. This document describes how to gain access to the web service, the input and output parameters of the available requests, and how to request technical support.


Required Steps for Integrating Worldwide Express Web Services

Details for accessing Worldwide Express Speedfreight Web Service are defined within the Web Services Definition Language (WSDL) file that is part of the Worldwide Express Developer Kit. Most modern development environments include support for automatically importing WSDL files and generating skeleton code to access the services. Although the specific details depend on the particular development environment, the general procedure is as follows:

1. Import the WSDL files into the development APIs of choice. Depending on the specific API, this step will result in skeleton code (such as Java or C# classes) for accessing the Web Service. An excellent free tool for working with WSDL files is SoapUI, which can be downloaded from http://www.soapui.org. Soap UI will allow you to import any WSDL file and generate test requests to a web service.

2. Develop your application, or modify your existing application, to incorporate the skeleton code.

3. Test the application and/or web site to ensure you receive the desired results.

4. Deploy your application and/or website.


Development and Test Environment

To begin working with the WSDL file in a development and test environment, use the following credentials to authenticate:

Username: testwwews Password: t420Bz Authentication Key: j4jx7wvrDDPtydjg Test Account Number: W317599416

The WSDL file that accompanies the Developer’s Kit is preset to point to the Worldwide Express test environment. Please verify that the endpoint is set to:

http://uat.wwex.com:8090/webServices/services/SpeedFreightShipment

Load testing, if performed, is permitted only while your application is generating web service transactions in the Worldwide Express development environment. Load testing while pointed to the production environment will generate financial transactions, payment for which will be the responsibility of the account holder. Worldwide Express must be notified a minimum of one week in advance of any intended load testing event, and load testing should not commence until confirmation is returned. Load testing notifications should be emailed to [email protected]. Your Worldwide Express account number, Speedship username, and the desired date and hours of the intended load test must be included in your email.

Once your application has been developed and tested, you can request to have your web services access switched to the Worldwide Express production environment. Email the request to [email protected], and include your Worldwide Express account number, Speedship username, and the web address (URL) of your application.

You will receive an email confirming that your account has been enabled in the production environment. Afterwards, change the web services endpoint to the production environment and replace the test account credentials with those associated with your account:

1. Change the endpoint to, http://www.wwexship.com/webServices/services/SpeedFreightShipment

2. Change the username to the Speedship username provided by your Worldwide Express representative.

3. Change the password to the Speedship password provided by your Worldwide Express representative.

4. Change the authentication key to the one associated with your account number. If you haven’t obtained your authentication key, please follow the instructions in the next section titled, “How to Obtain an Authentication Key”.

5. Change the account number to the account number provided by your Worldwide Express representative.


Your application will now be generating transactions in the production environment.


How to Obtain an Authentication Key

To access the web service you must obtain an Authentication Key. This is accomplished by logging into Speedship (speedship.wwex.com) and navigating to Services > Web Services. If you are unaware of your Speedship credentials, please contact your local Worldwide Express office or sales person.

You will be presented with the page shown in Illustration 1. From this page you can download the Developer’s Kit for this web service and other web services offered by Worldwide Express. Each kit is comprised of a Developer’s Guide, and WSDL file.

Illustration 1

To request an Authentication Key, click the Request Authentication Key button located at the bottom right hand corner of this page.

You will be prompted to complete the following form (Illustration 2):

Illustration 2

The Business Sponsor is the individual who is the non-technical sponsor of, or contact for, the project. The Development Contact is the individual who is the primary developer or programmer assigned to the project. If the Development Contact is a contracted third party, please provide the name of the company that employs the Development Contact.


This information is important for providing notices of updates to the web service, and for technical support.

Once the request is submitted, an email will be sent to the provided email addresses containing the Authentication Key. This is typically received within two hours.


Web Services Definition Language (WSDL)

XML and SOAP are general technologies used widely for many different purposes. The technology that ties them specifically to Web Services is the Web Services Definition Language (WSDL). Enterprises that make Web Services available to other enterprises describe those services using WSDL. In effect, WSDL acts as a service contract: it defines exactly what services the enterprise offers and how clients should access those services.

WSDL files are XML documents that conform to a specific structure. A current version of the WSDL specification is available as a draft submitted to the World Wide Web Consortium. It can be found on their web site at http://www.w3.org/TR/wsdl.

Although WSDL files, like all XML documents, are ultimately textual information, they are not primarily intended for humans to read. Instead, WSDL files are designed to be read by software applications and application development APIs. An application API such as Microsoft’s Visual Studio can import a WSDL file and automatically generate software classes that access the Web Services the WSDL defines. Developers then add these classes to their applications, giving the programs the ability to use Web Services.

Some WSDL files are published in special directories such as the Universal Description, Discovery, and Integration (UDDI) registry on the Internet. Worldwide Express does not currently publish WSDL documents for Worldwide Express Developer APIs in such directories. Instead, Worldwide Express delivers the WSDL files as part of the software development kit.


Getting Technical Support

Technical Support is provided by email. Questions should be sent to [email protected]. Please include the following information:

Subject Line

• The name of the web service you are trying to consume. This will ensure that the proper support professional is responding to your request. The name of this web service is the Speedfreight Web Service.

Detail Section

• Full contact information. It is important that we are able to contact you by telephone or email when responding to your request.

• Detailed description of the issue. The more thorough you are, the more quickly we can get the problem solved. If the issue is with your code, paste a copy of your code into your email. Screen captures are also very helpful when relevant.

• If this is concerning an error code, please list all of the circumstances under which the error is returned. One circumstance may not be more important than another, so listing all conditions will help us better serve your needs.


Overview

The Worldwide Express Speedfreight Web Service accommodates 4 types of services:

1. quoteSpeedFreightShipment will retrieve rate estimates and transit time information for LTL carriers serving a given origin and destination, based on the parameters provided.

2. bookSpeedFreightShipment converts a quote from among the choices provided in the FreightShipmentQuoteRequest service into a shipment and returns a Bill of Lading number and label image. The successful completion of this transaction schedules the shipment with the selected carrier.

3. voidSpeedFreightShipment is used to void a previously scheduled shipment.

4. freightShipmentProNumberRequest retrieves carrier PRO numbers for a given set of valid BOL numbers.


Get Quote Request

The quoteSpeedFreightShipment service will retrieve rate estimates and transit time information for LTL carriers serving a given origin and destination, based on the parameters provided.

Input Parameters The Worldwide Express Speed Freight Shipment Web Service has the following parameters available for quoteSpeedFreightShipment request: 1. loginId: Speedship/Speedfreight login (Required) 2. password: Speedship/Speedfreight password (Required) 3. licenseKey: Key to access Worldwide Express Freight Quote Webservice (Required) 4. accountNumber: Worldwide Express W-account number (Required) 5. senderCity (Optional) 6. senderState (Required) 7. senderZip (Required) 8. senderCountryCode (Optional) - Default value “USA” 9. receiverCity (Optional) 10. receiverState (Required) 11. receiverZip (Required) 12. receiverCountryCode (Optional) – Default value “USA” 13. insidePickup: Y/y if inside pickup required (Optional) 14. insideDelivery: Y/y if inside delivery required (Optional) 15. liftgatePickup: Y/y if liftgate pickup required (Optional) 16. liftgateDelivery: Y/y if liftgate delivery required (Optional) 17. residentialPickup: Y/y if residential pickup required (Optional) 18. residentialDelivery: Y/y if residential delivery required (Optional) 19. tradeshowPickup: Y/y if trade show pickup required (Optional) 20. tradeshowDelivery: Y/y if trade show delivery required (Optional) 21. constructionShitePickup: Y/y if construction site pickup required (Optional) 22. constructionSiteDelivery: Y/y if construction site delivery required (Optional) 23. notifyBeforeDelivery: Y/y if notification before delivery required (Optional) 24. limitedAccessPickup: Y/y if limited access pickup required (Optional) 25. limitedAccessPickupType: School (01), Church (02), Military Base/Installation (03) ,

Prison/Jail/ Correctional Facility (04) – If 24 is Y/y then 25 is required. (Conditional) 26. limitedAccessDelivery: Y/y if limited access delivery required (Optional) 27. limitedAccessDeliveryType: School (01), Church (02), Military Base/Installation

(03) , Prison/Jail/ Correctional Facility (04) – If 26 is Y/y then 27 is required. (Conditional)

28. collectOnDelivery: Y/y id COD service requested (Optional)


29. collectOnDeliveryAmount: valid $ amount for COD if COD service requested. (Conditional)

30. CODIncludingFreightCharge: Y/y if COD amount to be included in the freight charges. (Optional)

31. shipmentDate: date of shipment pickup (Optional) – format: mm/dd/yyyy. 32. insuranceDetail: (Optional)

a. insuranceCategory: description of product category (Optional) Value Description Category

1. New General Merchandise 2. Used General Merchandise 3. Fragile goods 4. Non-Perishable Foods/Beverages/Commodities 5. Perishable/Temperature Controlled/Foods/Beverages/Commodities (Full

Conditions) 6. Laptops/Cellphones/PDAs/iPads/Tablets/Notebooks and Gaming

systems 7. Wine 8. Radioactive/Hazardous/Restricted or Controlled Items Based on the description of your commodity from the categories above, use the relevant Code value. b. insuredCommodityValue: valid $ amount for insurance (Conditional). If 32

is used 33 must be used. c. insuranceIncludingFreightCharge: Y/y if insurance charges to be included

with the freight charges. (Optional) 33. commdityDetails: Commodity details (Required)

a. is11FeetShipment: Y/y is shipment is greater than 11 feet. b. handlingUnitDetails: Commodity Handling Unit Details (Required) c. wsHandlingUnit: (1..n) (Required)

i. typeOfHandlingUnit: valid values: Pallet, Skid, Bag, Bale, Box, Bundle, Carton, Crate, Cylinder,

1. Drum, Gaylord, Loose, Pails, Roll, Other. (Required) ii. numberOfHandlingUnit: the number of handling units of type I present

in your shipment. iii. handlingUnitHeight: Height of the handling unit (Optional) iv. handlingUnitLength: Length of the handling unit (Optional) v. handlingUnitWidth: Width of the handling unit (Optional)

vi. lineItemDetails: Line items in the handling unit. (Required) A. wsLineItem: (1..n) (Required)

aa. lineItemClass: valid freight class for the line item (50,55,60,65,70, 77.5, 85, 92.5, 100,125, 150,200,300,400,500) (Required)

ab. lineItemWeight: Weight of the line item. (Required) ac. lineItemDescription: Description of the line item

(Required)


ad. lineItemNMFC: NMFC number of the line item (Optional)

ae. lineItemPieceType: valid package/piece type for the line item (Bag, Bale, Box, Bucket,Pail, Bundle, Can, Carton, Case, Coil, Crate, Cylinder, Drums, Gaylord, Other, Pallet, Pieces, Reel, Roll, Tote, Tube. (Conditional based on the handling unit type – Pallet and Skid handling unit types require a piece type.)

af. piecesOfLineItem: number of pieces for the line item. (Conditional – if ae present then af is required)

ag. isHazmatLineItem: Y/y if the line item is hazmat. (Optional)

ah. lineItemHazmatInfo: Optional/Conditional – if ag is Y/y then ah is required)

1) lineItemHazmatUNNumberHeader: (Conditonal) valid values – UN #, ID #, NA #.

2) lineItemHazmatUNNumber: valid hazmat UN number (Conditonal)

3) lineItemHazmatClass: valid hazmat class (1, 2.1, 2.2, 2.3, 3, 4.1, 4.2, 4.3, 5.1, 5.2, 6.1, 6.2, 7, 8., 9) (Optional)

4) lineItemHazmatEmContactPhone: hazmat contact phone number (Required)

5) lineItemHazmatPackagingGroup: hazmat packaging group (I, II, III) (Optional)


Output Parameters

The Worldwide Express Speed Freight Shipment Web Service has the following parameters in the response to a successful quoteSpeedFreightShipment request: 1. ResponseStatusCode: 1/0 2. ResponseStatusDescription: Success/Failure 3. freightShipmentQuoteResults: (0..n carriers returned if sucessful) a. freightShipmentQuoteResult: (Quote Result details for each individual carrier) 1) shipmentQuoteId: Use this ID to book the shipment with the carrier of choice) 2) carrierSCAC

3) carrierName 4) totalPrice 5) transitDays 6) guaranteedService: Y/N 7) highCostDeliveryShipment: Y/N 8) interline: Y/N 9) nmfcRequired: Y/N


Book Shipment Request

The bookSpeedFreightShipment service converts a quote from among the choices provided in the FreightShipmentQuoteRequest service into a shipment and returns a Bill of Lading number and label image. The successful completion of this transaction schedules the shipment with the selected carrier.

Input Parameters The Worldwide Express Speed Freight Shipment Web Service has the following parameters available for bookSpeedFreightShipment request: 1. loginId: Speedship/Speedfreight login (Required) 2. password: Speedship/Speedfreight password (Required) 3. licenseKey: Key to access Worldwide Express Freight Quote Webservice (Required) 4. accountNumber: Worldwide Express W-account number (Required) 5. shipmentQuoteId: shipment quote id from the quote request. (Required) 6. freightShipmentSenderDetail: sender address details for shipment. (Required)

a. senderCompanyName (Required) b. senderAddressLine1 (Required) c. senderAddressLine2 (Optional) d. senderCity (Required) e. senderState (Required) f. senderZip (Required) g. senderCountryCode (Optional) - Default value “USA” h. senderPhone (Required) i. senderContact (Optional) j. emailBOLToSender: Y/y (optional) k. senderEmailAddess: Valid email address where the BOL image is to be

emailed to the sender (Conditional) 7. freightShipmentReceiverDetail: receiver address details for shipment (Required)

a. receiver CompanyName (Required) b. receiver AddressLine1 (Required) c. receiver AddressLine2 (Optional) d. receiver City (Required) e. receiver State (Required) f. receiver Zip (Required) g. receiver CountryCode (Optional) - Default value “USA” h. receiver Phone (Required) i. receiver Contact (Optional) j. emailBOLToReceiver: Y/y (optional)


k. receiver EmailAddess: Valid email address where the BOL image is to be emailed to the receiver (Conditional)

l. billToReceiver: Y/y bill shipment to valid WWE receiver account #. (Optional)

m. receiverAccountNumber: valid WWE account #. (conditional – if l is present then m is required)

8. shipmentDate: ( Required) format – mm/dd/yyyy. 9. shipmentReadyTime: (Required) format – 12 hr format hour : minutes am/pm. 10. shipmentClosingTime: (Required) format – 12 hr format hour : minutes am/pm. 11. freightShipmentCODInfo: (Conditional) if COD was selected for the quote id while

doing the shipment quote then 11 is required. a. companyName (Required) b. streetAddress (Required) c. city (Required) d. state (Required) e. zip (Required) f. country (Optional) g. formOfPayment: valid COD form of payment (Required) Value Description

1. Money Order 2. Bank Certified Check 3. Company Check 4. Personal Check

12. freightShipmentInsuranceDescription: (Conditional) If the quote id to be booked was

quoted with insurance, then 12 is required. a. insuranceDescriptionOfCargo: description of insured commodity (Required) b. insuranceMarksNumbers: marks and numbers for insured commodity

(Required) 13. shipmentReferences: (Optional)

a. freightShipmentReference (0..n) (Optional) i. referenceDescription (Required) ii. referenceType (Required) valid values: -

Description Value Accounting Code AC Bill of Lading Number BOL Booking Number BN Carton Number CA


Charge Department CD Creator CR Contract Number CT Cost Center CC Customer Number CS Customer Order Number CO Delivery Number DJ Factura Number FA Freight Collected FC General Ref Number RN Loading Number LO Manifest Number MN Pedimento Number PN Promotional Deal PD Purchase Order Number PO Requested Arrival Date E Return Authorization QJ Seal Number SN Sellers Invoice Number IV Transporation Control Number TN

iii.referencePackageNumber: (Optional)

14. specialInstruction: special instructions for the shipment (288 characters max) (Optional)

15. freightShipmentAddressLabel: Y/y if address labels requested. (Optional)

a. printShipmentAddessLabel: Y/y (Conditional) b. numberOfShipmentAddressLabel: number of address labels requested)

(conditional)


Output Parameters

The Worldwide Express Speed Freight Shipment Web Service has the following parameters in the response to a successful bookSpeedFreightShipment request: 1. ResponseStatusCode: 1/0 2. ResponseStatusDescription: Success/Failure 3. freightShipmentBOLNumber: WWE BOL # of the shipment if successful. 4. freightShipmentBOLLabels: base 64 encoded image of the BOL pages.


Void Shipment Request

Ths voidSpeedFreightShipment service is used to void a previously scheduled shipment.

Input Parameters The Worldwide Express Speed Freight Shipment Web Service has the following parameters available for voidSpeedFreightShipment request:

1. loginId: Speedship/Speedfreight login (Required) 2. password: Speedship/Speedfreight password (Required) 3. licenseKey: Key to access Worldwide Express Freight Quote Webservice

(Required) 4. accountNumber: Worldwide Express W-account number (Required) 5. freightShipmentBOLNumber: 1 or more BOL numbers that you need to

cancel (void). (Required)

Output Parameters

The Worldwide Express Speed Freight Shipment Web Service has the following parameters in the response to a successful voidSpeedFreightShipment request: 1. ResponseStatusCode: 1/0 2. ResponseStatusDescription: Success/Failure 3. freightShipmentVoidResult:

a. bolNumber: BOL # from request. b. Description: true/false. Notifying whether the void request succeeded.


PRO Number Request

The freightShipmentProNumberRequest service retrieves carrier PRO numbers for a given set of valid BOL numbers.

Input Parameters The Worldwide Express Speed Freight Shipment Web Service has the following parameters available for freightShipmentProNumberRequest request:

1. loginId: Speedship/Speedfreight login (Required)

2. password: Speedship/Speedfreight password (Required)

3. licenseKey: Key to access Worldwide Express Freight Quote Webservice (Required)

4. accountNumber: Worldwide Express W-account number (Required)

5. freightShipmentBOLNumber: 1 or more BOL numbers that you need to get PRO #’s for. (Required)

Output Parameters

The Worldwide Express Speed Freight Shipment Web Service has the following parameters in the response to a successful freightShipmentProNumberRequest request:

1. ResponseStatusCode: 1/0 2. ResponseStatusDescription: Success/Failure 3. freightShipmentProNumberResult:

a. bolNumber: BOL # from request. b. proNumber: PRO # for BOL # in a.

speedfreight web service developer guide updated november ... › wp-content › uploads › ... ·...

Documents