ESHIPPER API DOCUMENTATION V3.0.2 Revision Log Date Oct 12, 2006 Oct 30, 2006 Jan 11, 2007 Jan 11, 2007 Jan 11, 2007 Jun 20, 2007 Dec 5, 2007 Jan 20, 2007 Jan 24, 2007 Version 2.0.1 2.0.2 2.0.3 2.0.3 2.0.3 2.0.4 2.0.5 2.0.6 2.0.7 Modifications Added Purolator Ground 9AM and 1030 services. Added all DHL services. COD and Insurance Handling for DHL Services (See section 8.1). Scheduled Ship Date option (See section 8.2). Saturday Service option Services (See section 8.3). Returning tracking URL in ShippingReply • FedEx USA service Ids added • UPS services added Canada Post services added. • Added FedEx Express Saver Service. • Updated API and schema to return label image (PNG) if available (see section 5.4). • Added new API call – ShipmentCancelRequest (see section 6). • Added new API call – OrderInformationRequest (see section 7). • Insurance amounts and COD amounts to be sent at package level (as opposed to order level). See section 8.1 • Added UPS services in USA • Added LTL services in USA and Canada • Removed DHL USA Domestic Services. • Changed test server URL Added Version Management (See section 3.1) • Returning currency code attribute with Quote element.(See section 4.1) • Returning Original Charge and Applicable Charge with OrderInformationReply (See Section 7.1) • Returning Pickup confirmation number with ShippingReply and OrderInformationReply (See Section 5.6/7.2) Added additional services:• Schedule Pickup (See section 8.4), • Signature Required (See section 8.5), • Hold for Pickup Required (See section 8.6), • Delivery Appointment (See section 8.7), • Special Equipment (See section 8.8), • Inside delivery (See section 8.9), • Freight Class and Type (See section 8.10) • Insurance Type (See section 8.11) Updated status values February 12, 2007 2.0.8 April 15, 2008 2.0.9 March 01, 2009 2.1.0 3.0.0 3.0.0 3.0.0 October 21, 2009 3.0.2 1. Introduction This document outlines the details of the API specifications for integrating with the EShipper application. The EShipper API is a work in progress, and it is expected that some minor changes may be made to the API before a fully stable version is released. The protocol of communication between the client and the EShipper application will be based on XML technology. Currently, the EShipper will handle 4 types of requests from the client, (i) Quote Request, (ii) Ship Request, (iii) Order Information Request, and (iv) Cancel Order Request. All requests will be sent via the client in XML format, and the EShipper application will respond to these requests in XML format. 2. Set up Process Any customer willing to use the XML API will require to be registered with the application first. Please contact EShipper administrator or your sales representative to ensure that you have been set-up on the application. A special password will then be provided to the customer, which will be sent in the request along with the customer name. The EShipper application will use the customer name and password to authenticate the request before processing it. All requests will be sent to the URL www.e-shipper.net/rpc2 . Customers can also use the test server to post test requests. The URL for the test server is http://test.eshipper.com:2201/eshipper/rpc2 . 3. XML Schema The XML schema for the EShipper API is shown below. This schema contains definitions for elements and attributes used in the 8 message types:- (i) QuoteRequest, (ii) QuoteReply, (iii) ShippingRequest, (iv) ShipReply, (v) ShipmentCancelRequest, (vi) ShipmentCancelReply, (vii) OrderInformationRequest, and (viii) OrderInformationReply. 3.1 Version Management (since v3.0.0) The use of “version” in the root element has been introduced as of v3.0.0. For all requests, version information will have to be sent in the element. Example of version in the EShipper element: XSD file containing the schema is included in this package. 4. Getting a Quote In order to receive a quote from the EShipper API, the client can send a “QuoteRequest” message to the API. The API will process the request and return a “QuoteReply” message. The elements and attributes required by the “Quote” request and response messages are shown in the schema above. A sample request and response is shown below:- Available Tags with Attributes in the QuoteRequest • QuoteRequest [Required] o o o serviceId [Optional] dangerousGoodsType [Optional] isSaturdayService [Optional] • o signatureRequired [Optional] o holdForPickupRequired [Optional] o specialEquipment [Optional] o deliveryAppointment [Optional] o insideDelivery [Optional] o scheduledShipDate [Optional] o insuranceType [Optional] From [Required] • • • • • • o id [Required] o company [Required] o address1 [Required] o city [Required] o state [Required] o country [Required] o zip [Required] To [Required] o id [Required] o company [Required] o address1 [Required] o city [Required] o state [Required] o country [Required] o zip [Required] COD [Optional] o paymentType [Required] CODReturnAddress [Required if COD is selected] o codCompany [Required] o codName [Required] o codAddress1 [Required] o codCity [Required] o codStateCode [Required] o codZip [Required] o codCountry [Required] Packages [Optional][Required if type=”Package” or “Pallet”] o type [Required] Package [Optional][Required if type=”Package” or “Pallet”] o length [Required] o width [Required] o height [Required] o weight [Required] o type [Optional][Required if type “Pallet”] o freightClass [Optional] [Required if type=“Pallet”] o insuranceAmount [Optional] o codAmount [Optional] o description [Optional][Required if type=“Pallet”] Pickup [Optional] o contactName [Required] o phoneNumber [Required] o pickupDate [Required] o pickupTime [Required] o closingTime [Required] o location [Optional] Sample QuoteRequest message Sample QuoteReply response to QuoteRequest message 4.1 Currency Code (since v3.0.0) The API will return currency code attribute in the Quote response. This attribute will be return in the Quote element. Example of currency code in the Quote element: 5. Shipping an Order In order to ship an order using the EShipper API, the client can send a “ShippingRequest” message to the API. The application then attempts to ship the order using the information provided. If a serviceId is specified in the request, the application will attempt to ship the order using that service only. If no serviceId attribute is specified, the application will retrieve rates for all eligible services and will ship using the cheapest fastest service available, i.e. it will first filter the services by the fastest and then pick the cheapest amongst these. Available Tags with Attributes in the ShippingRequest • ShippingRequest [Required] o serviceId [Optional] o dangerousGoodsType [Optional] o isSaturdayService [Optional] o signatureRequired [Optional] o holdForPickupRequired [Optional] o specialEquipment [Optional] o deliveryAppointment [Optional] o insideDelivery [Optional] o scheduledShipDate [Optional] o insuranceType [Optional] From [Required] • • • • • • • • o id [Required] o company [Required] o address1 [Required] o city [Required] o state [Required] o country [Required] o zip [Required] To [Required] o id [Required] o company [Required] o address1 [Required] o city [Required] o state [Required] o country [Required] o zip [Required] Payment [Required] o type [Required] Reference [Optional] o name [Required] o code [Required] COD [Optional] o paymentType [Required] CODReturnAddress [Required if COD is selected] o codCompany [Required] o codName [Required] o codAddress1 [Required] o codCity [Required] o codStateCode [Required] o codZip [Required] o codCountry [Required] Packages [Optional][Required if type=”Package” or “Pallet”] o type [Required] Package [Optional][Required if type=”Package” or “Pallet”] o length [Required] o width [Required] o height [Required] o weight [Required] o type [Optional][Required if type “Pallet”] o freightClass [Optional] [Required if type=“Pallet”] • • • • • o insuranceAmount [Optional] o codAmount [Optional] o description [Optional][Required if type=“Pallet”] Pickup [Optional] o contactName [Required] o phoneNumber [Required] o pickupDate [Required] o pickupTime [Required] o closingTime [Required] o location [Optional] CustomsInvoice [Optional] [Required if International shipment.] BillTo [Required] o company [Required] o name [Required] o address1 [Required] o city [Required] o state [Required] o zip [Required] o country [Required] Contact [Required] o name [Required] o phone [Required] Item [Required] o code [Required] o description [Required] o originCountry [Required] o quantity [Required] o unitPrice [Required] Sample ShippingRequest message Sample ShippingReply response to ShippingRequest message http://www.fedex.com/Tracking?tracknumbers=052 800410000484 [base-64 encoded String] [base-64 encoded String] As seen in the request above, the serviceId was set to “3” which implies that a “FedEx Ground” shipment was requested (see section on “Services” for more information on this feature). The application performed the shipment and returned the tracking numbers for the packages along with the carrier and service information. 5.1 Labels The labels are returned in Acrobat PDF format as a base-64 encoded string inside the tag. In order to recreate the labels on the client side, the client will have to read the characters enclosed inside this “Labels” tag, decode it using a base-64 decoding algorithm (which is readily available on most platforms), and then create an Acrobat PDF file from the resulting bytes. Please see appendix A for some examples on this process. 5.2 Customs Invoice If customs invoice information is submitted in the shipping request, it is returned in Acrobat PDF format as a base-64 encoded string inside the tag. In order to recreate the customs invoice on the client side, the client will have to read the characters enclosed inside this “CustomsInvoice” tag, decode it using a base-64 decoding algorithm (which is readily available on most platforms), and then create an Acrobat PDF file from the resulting bytes. Please see appendix A for some examples on this process. 5.3 Tracking URL (since v2.0.4) The API will return a tracking URL in the ShippingReply response. This URL can be used to track the shipment on the carrier’s website. If no tracking URL is available, then the API will return an empty string. 5.4 Label Images (since v2.0.7) The API returns label images if the images are available from the carrier. Currently, the API returns PNG images only. For multi-package shipments the API will return one label image per package. The images are sent under the element. Each label will have its own element, containing sub-elements and . The image data is contained in the element as a base-64 encoded string (similar to the PDF data). The contents of the element will have to be decoded using Base-64 decoding algorithm. For example, a shipment with 2 packages will return images in the following method: PNG [base-64 encoded String] PNG [base-64 encoded String] 5.5 Quote (since v3.0.0) The API will return a Quote element in the ShippingReply response. The Quote element contains the rate information about the shipment. 5.6 Pickup confirmation number (since v3.0.0) The API will return a Pickup element in the ShippingReply response. The Pickup element contains the pickup confirmation number of the pickup request. The attribute confirmationNumber is optional. 6. Shipment Cancel Request In order to cancel an order that was previously created using the EShipper API, the client can send a “ShipmentCancelRequest” message to the API. The system will attempt to cancel the order based on the ‘orderId’ provided in the request. A success or error message will be returned depending on the result of the request. A status of ‘4’ indicates that the shipment was cancelled. For a list of status mappings, please see Appendix B, section 10.1. Sample ShipmentCancelRequest message Sample ShipmentCancelReply response to ShipmentCancelRequest message 7. Order Information Request Information on orders that were previously created can be requested using the ‘OrderInformationRequest’. This request will return all the fields from the ‘ShippingReply’, plus a status element containing the status Id and corresponding status name for the order. For a list of status mappings, please see Appendix B, section 10.1. Sample OrderInformationRequest message