XML TrackRequest/Response & … · FedEx Ship Manager® API XML TrackRequest/Response & TrackShipmentRequest/Response Transaction Mapping Guide June 2006

FedEx Ship Manager® API

XML TrackRequest/Response & TrackShipmentRequest/Response

Transaction Mapping Guide

June 2006

Confidential and Proprietary

The information contained in this XML Transaction Mapping Guide is confidential and proprietary to FedEx® Corporate Services, Inc. and its affiliates (collectively "FedEx"). No part of this XML Transaction Mapping Guide may be distributed or disclosed in any form to any third party without written permission of FedEx. This guide is provided to you under and its use is subject to the terms and conditions of the FedEx End User and/or Consultant License Agreement. The information in this document may be changed at any time without notice. Any conflict between either of these guides, the FedEx End User and/or Consultant License Agreement, and the FedEx Service Guide shall be governed by the FedEx End User and/or Consultant License Agreement and the FedEx Service Guide, in that order.

© 2006 FedEx. FedEx and the FedEx logo are registered service marks. All rights reserved. Unpublished.

Introduction

Introduction

FedEx Ship Manager® API XML Tracking Mapping Set

The objective of the FSM API Tracking Mapping Guide is to provide information on how tracking data will be populated in the Tracking Responses for TrackRequest and TrackShipmentRequest after June 17, 2006. This guide will also outline the benefits to upgrading your Tracking transaction and provide a high-level scope of the impact of migrating from the TrackRequest/TrackResponse or the TrackShipmentRequest/TrackShipmentResponse Tracking transaction to the latest FDXTrack2Request/FDXTrack2Reply Tracking transaction supported by FedEx Ship Manager API.

Why should you upgrade your tracking transaction?

Here are a few reasons:

• Support for FedEx Express®, FedEx Ground®, FedEx Freight®, FedEx® Cargo, and FedEx Custom Critical® tracking services

• Additional tracking options • Improved performance • Elimination of support for the TrackRequest or TrackShipmentRequest

Error Code Listing

For a complete API error code listing, see the Tagged and XML Transaction Error Codes and Messages list located at http://fedex.com/us/solutions/shipapi/docs.html.

Transaction Interface

See the FedEx Ship Manager API XML Transaction Guide located at http://fedex.com/us/solutions/shipapi/docs.html for a detailed API transaction listing.

FedEx Ship Manager® API XML TrackRequest & TrackShipmentRequest Transaction Mapping Guide 1

http://fedex.com/us/solutions/shipapi/docs.html

http://fedex.com/us/solutions/shipapi/docs.html

TrackRequest/TrackResponse

It should be noted, the existing customer request will remain unchanged. Only the response back to the customer will have an impact. Refer to the chart below to determine what data will no longer be provided within the XML TrackResponse.

TrackRequest TrackResponse Availability of element returned in

response *N/A (Not Available)

TRACKPROFILE SearchValue

SearchType TrackingNumber

CarrierType Number Available

StartDateRange FormID N/A

EndDateRange MASTERTRACKINGNUMBER

ShipperAccountNumber Number Available

Version FormID Available

ShipperAccountNumber N/A

CarrierType Available

ShipDate Available

EstimatedDeliveryDate Available

EstimatedDeliveryTime Available

DestinationCity Available

DestinationState Available

DestinationZipCode Available

CountryCode Available

DeliveredDate Available

DeliveredTime Available

SignedForBy Available

ServiceCode Available

WEIGHT

Amount Available

Units Available

PackageCode Available

PackageDescription Available

ReAttemptDate Available

ReAttemptTime Available

Reference Available

FedExURL Available

SCAN

DeliveryInfo

Address N/A

StatusCode N/A

StatusDescription N/A


TrackRequest/TrackResponse

Availability of element returned in response TrackRequest TrackResponse

*N/A (Not Available) ScanDelayInfo

Type N/A

City N/A

StateorCountryCode N/A

Date N/A

Length N/A

ScanType Available

ScanDescription Available

StatusCode Available

StatusDescription Available

City Available

State Available

PostalCode Available


LocationCode Available

Date Available

Time Available

CageComment N/A

DeliveryAddress N/A

ERROR

Code Available

Message Available


TrackShipmentRequest/TrackShipmentResponse


It should be noted, the existing customer request will remain unchanged. Only the response back to the customer will have an impact. Refer to the chart below to determine what data will no longer be provided within the XML TrackShipmentResponse.



SearchValue CustomerTransactionIdentifier Available

ERROR SearchType

CarrierType Code Available

StartDateRange Message Available

EndDateRange MoreDataFlag Available

ShipDate PagingToken Available

TRACKPROFILE ShipperAcountNumber

DestinationCountryCode TrackingNumber Available

CustomerTransactionIdentifier Carrier Available

Paging Token RelationshipGroupCount Available

RELATIONSHIPGROUP Version

Detail Scan Indicator RelationshipType Available

RelationshipValue Available

ShipDate Available

EstimatedDeliveryDate Available

EstimatedDeliveryTime Available

DestinationCity Available

DestinationState Available

DestinationZipCode Available

DestinationCountryCode Available

DeliveredDate Available

DeliveredTime Available

SignedForBy Available

DeliveredLocationCode Available

DeliveredLocationDescription Available

Service Available

WEIGHT

Amount Available

Units Available

PackageDescription Available

ReattemptDate Available

ReattemptTime Available

PackagingSequenceNumber Available






TotalPieces Available

FedExURL Available

ScanCount Available

SCAN

Date Available

Time Available

ScanType Available

ScanDescription Available

StatusExceptionCode Available

StatusExceptionDescription Available

City Available

State Available


HoldAtLocationAddress N/A

ERROR Code Available

Message Available

FDXTrack2Request/FDXTrack2Reply


Use of the FedEx Ship Manager API FDXTrack2Request

In addition to the TrackRequest/Response and TrackShipmentRequest/Response, the FedEx Ship Manager API offers the newer FDXTrack2Request/FDXTrack2Reply. This guide is intended to assist you in upgrading to the latest tracking transaction.

The only requirements are: • Modify your code to use the FDXTrack2Request and FDXTrack2Reply schemas. Refer to the latest FedEx XML Transaction Guide, located on www.fedex.com. • Assign the correct Universal Transaction Identifier (UTI) code to the transaction. This is handled via the FedEx Ship Manager API application interface if used.

(Direct client users do not need to utilize UTI codes.) The correct UTI code for the FDXTrack2Request transaction is 2544 • The UTI code for the TrackRequest transaction is 2503 and the UTI code for the TrackShipment transaction is 2514.

FDXTrack2Request

When sending a shipment tracking Request to the FedEx servers, there is information that the server requires before it will process the Request. The following elements can be sent to the FedEx server in order to track by number or track by reference.

Element Name Applicable Carrier

Valid For

Data Type

Max Length Element Description/Requirements

REQUESTHEADER

RequestHeader / CustomerTransaction Identifier

FDXE FDXG FDXC FXCC FXFR

ALL xs:string 40 Optional. This element allows a FedEx customer to assign a unique identifier to a transaction. It is returned in the Reply transaction to aid in matching transaction Requests to Replies.

RequestHeader / AccountNumber FDXE FDXG FDXC FXCC FXFR

ALL xs:integer 12 The FedEx account number of the Sender is required to successfully receive a tracking response.

RequestHeader / MeterNumber FDXE FDXG FDXC FXCC FXFR

ALL xs:integer 10 The unique meter number assigned to the Sender’s FedEx account number is required to successfully receive a tracking response.




Valid For

Data Type


RequestHeader / CarrierCode FDXE FDXG FDXC FXCC FXFR

ALL xs:string 4 Required. Valid values: FDXE – FedEx Express Tracking Requests FDXG – FedEx Ground Tracking Requests FDXC – FedEx Cargo Tracking Requests FXCC – FedEx Custom Critical Tracking Requests FXFR – FedEx Freight Tracking Requests

Any one of several kinds of identifier(s) for which all packages will be tracked. PACKAGEIDENTIFIER

PackageIdentifier / Value FDXE FDXG FDXC FXCC FXFR

ALL xs:string 40 Required. An identifier that relates to one or more packages (or to the shipments of which they are part). Example : The Track Number for a Track By Number Request




Valid For

Data Type


PackageIdentifier / Type FDXE FDXG FDXC FXCC FXFR

ALL xs:string 32

Optional. Specifies the type of track desired on the “PackageIdentifier \ Value” element. Valid values:

• Tracking_Number _Or_Door Tag • EXPRESS_MPS_MASTER (Applicable to FDXE Only) • GROUND_SHIPMENT_ID (Applicable to FDXG Only) • RMA (Applicable for FDXE, FDXG) • TCN (becomes SHR, CUS) (Valid for Request only) • BOL (bill of lading) (Applicable for FXCC, FDXC, FXFR) • PARTNERCARNBR (Applicable to FXFR Only) • REF (Valid for Request only) • INV (Applicable for FDXG, FXFR) • PO (Applicable for FDXG, FXFR) • CUSTAUTHNUM (Applicable to FXFR Only) • CUR (Applicable for FDXG, FXFR) • DEPARTMENT (Applicable to FDXG Only) • PARTNUM (Applicable to FXCC Only) • SHR (Applicable for FDXE, FDXC, FXFR) • GOVBOL • COD • RETURNTOSHIPPER

* REF value is non-carrier specific and allows a search by Reference across all available Carrier Codes. Some Search Types limit the search to a carrier (i.e. FedEx Ground Shipment ID, Express MPS). If value is omitted from transaction, defaults to TrackingNumber _Or_Door Tag.

TrackingNumberUniqueIdentifier FDXE FDXG FDXC FXCC

ALL xs:string One of the TrackingNumberUniqueIdentifiers returned in a previous Reply. Only applicable in a request when trying to resolve a duplicate condition.




Valid For

Data Type


ShipDateRangeBegin FDXE FDXG FDXC FXCC FXFR

ALL xs:date 10 Optional, but recommended. If provided, ShipDateRangeEnd is required. Required entry of date range to find desired results for reference tracking number. If not provided, results may vary. Format: YYYY-MM-DD

ShipDateRangeEnd FDXE FDXG FDXC FXCC FXFR

ALL xs:date 10 Optional, but recommended. If provided, ShipDateRangeBegin is required. Format: YYYY-MM-DD

ShipmentAccountNumber FDXE FDXG FDXC FXCC FXFR

ALL xs:string 9 Optional, but recommended. Account number associated with shipment (as opposed to account number in RequestHeader, which is that of party sending request). If not specified, then the DestinationCountryCode and DestinationPostalCode (where applicable) are required.

DestinationCountryCode FDXE FDXG FDXC FXCC FXFR

ALL xs:string 2 Optional, but recommended. Country code of shipment destination. Required for Track by Reference when shipment Account Number is not provided

DestinationPostalCode FDXE FDXG FDXC FXCC FXFR

ALL xs:string 16 Optional, but recommended. Postal code of shipment destination. Required for Track by Reference when shipment Account Number is not provided and country is postal aware.

Language / LanguageCode FDXE FDXG FDXC FXCC FXFR

ALL xs:string 2 Optional. Alpha 2-character code of language desired for certain text elements in Reply. Defaults to EN (English).

Language / LocaleCode FDXE FDXG FDXC FXCC FXFR

ALL xs:string 2 Optional. Can be used to specify the dialect or sublanguage of some languages specified with the LanguageCode. Defaults to EN (English).

DetailScans FDXE FDXG FDXC FXCC FXFR

ALL xs:boolean Optional. Defaults to false If set to false or 0 – returns Summary/Profile data – Profile Only If set to true or 1 – returns Detail Scan Activity (multiple scan structure) for each package.




Valid For

Data Type


PagingToken FDXE FDXG FDXC FXCC FXFR

ALL xs:string variable Optional. This element is utilized to obtain additional data on second and subsequent FDXTrack2Request transactions when more related tracking information exists that exceed the capacity of any one response structure. This element should be absent from any first Track Request. It is only populated if the response results are more than one response structure worth of data. If the PagingToken element contains value in first FDXTrack2Reply, more tracking data exists. See the MoreDataFlag element in the FDXTrack2Reply. You should populate this element with the value returned in the PagingToken element of the previous Reply transaction.



FDXTrack2Reply


Valid For

Data Type


REPLYHEADER

ReplyHeader / CustomerTransaction Identifier


ALL xs:string 40 Returned if the customer included it in the Request transaction, and will contain the provided value in the FDXTrack2Request.

ERROR

Error / Code FDXE FDXG FDXC FXCC FXFR

ALL xs:string 8 Returned only if an error occurred while processing the transaction.

Error / Message FDXE FDXG FDXC FXCC FXFR

ALL xs:string 120 Returned only if an error occurred while processing the transaction. (English Only)

Error / LocalLanguageMessage FDXE FDXG FDXC FXCC FXFR

ALL xs:string 120 Error message returned when a transaction fails. Returned only if an error occurs and a non-English Reply Language Requested.

DuplicateWaybill FDXE FDXG FDXC FXCC

xs:boolean true if duplicate packages with the same tracking number have been found, and only limited data will be provided for each one.

MoreDataFlag FDXE FDXG FDXC FXCC FXFR

ALL xs:boolean Value of true or 1 indicates that more data exists. Returned when additional packages remain or exceed the single reply structure capacity.




Valid For

Data Type


PagingToken FDXE FDXG FDXC FXCC FXFR

ALL xs:string Variable A string that must be passed in a TrackRequest to retrieve the next set of packages.

Data pertaining to a single package that matches the PackageIdentifier given in the Request. PACKAGE

Package / TrackingNumber FDXE FDXG FDXC FXCC FXFR

ALL xs:string 20 Tracking number provided in the Request. Note: Door tag will never be returned in the response.

Package / SoftError

Package / SoftError / Type FDXE FDXG FDXC FXCC FXFR

ALL xs:string 25 Returned only if a soft error/warning message is available. Valid values:

• WARNING • INFORMATIONAL

Package / SoftError / Code FDXE FDXG FDXC FXCC FXFR

ALL xs:string 8 Returned only if a soft error/warning message is available.

Package / SoftError / Message FDXE FDXG FDXC FXCC FXFR

ALL xs:string 255 Returned only if a soft error/warning message is available.

Package / TrackingNumberUniqueIdentifier

FDXE FDXG FDXC FXCC

ALL xs:string

Completes the tracking number and can be used to uniquely identify a package in a follow-up Request. It is returned when duplicate waybills are found with the same tracking number.




Valid For

Data Type


Package / StatusCode FDXE FDXG FDXC FXCC FXFR

ALL xs:string 100

Package / StatusDescription FDXE FDXG FDXC FXCC FXFR

ALL xs:string 4

Package / ServiceCommitMessage FDXE ALL xs:string 4

Package / CarrierCode FDXE FDXG FDXC FXCC FXFR

ALL xs:string 4 Specifies the particular carrier the package was shipped. Valid values:

FDXE – FedEx Express Tracking Requests FDXG – FedEx Ground Tracking Requests FDXC – FedEx Cargo Tracking Requests FXCC – FedEx Custom Critical Tracking Requests FXFR – FedEx Freight Tracking Requests

PACKAGE / OTHERIDENTIFIER Another identifier that is related to this package.

Package / OtherIdentifier / Value FDXE FDXG FDXC FXCC FXFR

ALL xs:string 40 Required. An identifier that relates to one or more packages (or to the shipments of which they are part).




Valid For

Data Type


Package / OtherIdentifier / Type FDXE FDXG FDXC FXCC FXFR

ALL xs:string 32 Optional. Specifies the type of track identifer indicated in the Request. Some identifiers apply to a single package, while others apply to multiple packages or shipments. Valid values:

• Tracking_Number _Or_Door Tag • EXPRESS_MPS_MASTER (Applicable to FDXE Only) • GROUND_SHIPMENT_ID (Applicable to FDXG Only) • RMA (Applicable for FDXE, FDXG) • TCN (becomes SHR, CUS) (Valid for Request only) • BOL (bill of lading) (Applicable for FXCC, FDXC, FXFR) • PARTNERCARNBR (Applicable to FXFR Only) • REF (Valid for Request only) • INV (Applicable for FDXG, FXFR) • PO (Applicable for FDXG, FXFR) • CUSTAUTHNUM (Applicable to FXFR Only) • CUR (Applicable for FDXG, FXFR) • DEPARTMENT (Applicable to FDXG Only) • PARTNUM (Applicable to FXCC Only) • SHR (Applicable for FDXE, FDXC, FXFR) • GOVBOL • COD • RETURNTOSHIPPER

Package / Service FDXE

FDXG FDXC FXCC FXFR

ALL xs:string 70 String describing service type.

Package / Weight FDXE FDXG

ALL xs:decimal 6.1 Weight of the individual package. Format: One explicit decimal position (e.g. 5.0)

Package / ShipmentWeight FXFR FXCC FDXC FDXE

ALL xs:decimal 8.1 Gross weight of shipment of which this package is a part.




Valid For

Data Type


Package / WeightUnits FXFR FXCC FDXC FDXE FDXG

ALL xs :nmtoken 3 Valid values: • KGS • LBS

Package / PackagingDescription FDXE FDXG FDXC FXCC FXFR

ALL xs:string 20 Description of packaging type of this package. Returned upon successful Reply for only.

Package / PackageSequence Number FDXE INTL xs:string 4 Package sequence number of package in multiple-piece shipment. Returned upon successful Reply for FedEx Express international only.

Package / PackageCount FDXE FDXG

ALL xs:string 4 Count of packages in multiple-piece shipment.

PACKAGE / SHIPPERADDRESS Shipper address information.

Package / ShipperAddress / City FXFR FXCC

ALL xs:string 40 Name of the city to which the shipment is shipped.

Package / ShipperAddress / StateOrProvince Code

FXFR FXCC

ALL xs:string 2 State or province to which the shipment is shipped.

Package / ShipperAddress / PostalCode

FXFR FXCC

ALL xs:string 16 Postal code of the State or province to which the shipment is shipped. Must be numeric for U.S. No embedded dashes allowed. Valid characters: A-Z; 0-9; a-z

Package / ShipperAddress / CountryCode

FXFR FXCC

ALL xs:string 2 Name of the country to which the shipment is shipped.

PACKAGE / ORIGINLOCATIONADDRESS Origin location (carrier facility) address.

Package / OriginLocationAddress / City

FXFR FDXC

ALL xs:string 40 Name of the city to which the shipment is destined.

Package / OriginLocationAddress / StateOrProvince Code

FXFR FDXC

ALL xs:string 2 State or province to which the shipment is destined.

Package / OriginLocationAddress / PostalCode

FXFR FDXC

ALL xs:string 16 Postal code of the State or province to which the shipment is destined. Must be numeric for U.S. No embedded dashes allowed. Valid characters: A-Z; 0-9; a-z




Valid For

Data Type


Package / OriginLocationAddress / CountryCode

FXFR FDXC

ALL xs:string 2 Name of the country to which the shipment is destined.

Package / EstimatedPickupDate FXCC ALL xs:date 10 Projected pickup date.

Package / EstimatedPickupTime FXCC ALL xs:date 10 Projected pickup time.

Package / ShipDate FDXE FDXG FDXC FXCC FXFR

ALL xs:date 10 Date on which package was tendered to FedEx.

Package / TotalTransitDistance FXCC ALL xs:non negative integer

Package / DistanceToDestination FXCC ALL xs:non negative integer

Package / DistanceUnits FXCC ALL xs:non negative integer

Units in which TotalTransitDistance and DistanceToDestination are expressed. Valid values:

• KM • MI

PACKAGE / DESTINATIONADDRESS Destination address information.

Package / DestinationAddress / City FDXE FDXG FDXC FXCC FXFR

ALL xs:string 40 Name of the city to which the shipment is destined.

Package / DestinationAddress / StateOrProvince Code


ALL xs:string 2 State or province code to which the shipment is destined.

Package / DestinationAddress / PostalCode

FXCC ALL xs:string 16 Postal Code to which the shipment is destined. Returned if Destination Country Code is postal aware..




Valid For

Data Type


Package / DestinationAddress / CountryCode


ALL xs:string 2 Name of the country to which the shipment is destined.

PACKAGE / DESTINATIONLOCATIONADDRESS Destination location (carrier facility) address.

Package / DestinationLocationAddress / City

FXFR FDXC

ALL xs:string 40 Name of the city of the carrier facility for the package destination.

Package / DestinationLocationAddress / StateOrProvince Code

FXFR FDXC

ALL xs:string 2 State or province of the carrier facility for the package destination.

Package / DestinationLocationAddress / PostalCode

FXFR FDXC

ALL xs:string 16 Postal code of the State or province of the carrier facility for the package destination.

Package / DestinationLocationAddress / CountryCode

FXFR FDXC

ALL xs:string 2 Name of the country of the carrier facility for the package destination.

Package / EstimatedDelivery Date FDXE FDXG FXCC FXFR

ALL xs:date 10 Projected package delivery date based on ship date, service, and destination.

Package / EstimatedDelivery Time FDXE FDXG FXCC FXFR

ALL xs:time 10 Projected package delivery time based on ship date, service, and destination.

Package / DeliveredDate FDXE FDXG FDXC FXCC FXFR

ALL xs:date 10 Date when the package was delivered at destination.

Package / DeliveredTime FDXE FDXG FDXC FXCC FXFR

ALL xs:time Time when the package was delivered at destination.

TrackProfile / DeliveredLocation Code FDXE ALL xs:string 2 Pairs with DeliveredLocation Description element. Returned upon successful Reply only.




Valid For

Data Type


TrackProfile / DeliveredLocation Description

FDXE ALL xs:string 25 Relative location at which package was left, such as Front Desk or Back Door. Pairs with Delivered LocationCode element. Returned upon successful Reply only.

Package / SignedForBy FDXE FDXG FDXC FXCC FXFR

ALL xs:string 40 Signature of person who signed for packages, or relative location at which package was left, such as Front Desk or Back Door.

Package / SignatureProofOfDeliveryAvailable

FDXE FDXG

USD/ ALL

xs :boolean Whether image of signature given upon delivery is available.

Package / PODNotificationsAvaiilable FDXE FDXG FXFR

ALL xs :boolean True if and only if Proof Of Delivery Notifications are available.

Package / ExceptionNotificationsAvailable

FDXE FDXG FXFR

ALL xs :boolean True if and only if Exception Notifications are available.

PACKAGE / SPLITSHIPMENTPART A portion of a shipment that has been split across vehicles; will not be returned if the parts have been rejoined or if all have been delivered. Count of pieces or skids traveling together.

Package / SplitShipmentPart / Date FDXC ALL xs:date 10

Package / SplitShipmentPart / Time FDXC ALL xs:time 6

Package / SplitShipmentPart / StatusCode

FDXC ALL xs:string 4

Package / SplitShipmentPart / StatusDescription

FDXC ALL xs:string 100

PACKAGE / EVENT One scan or other event related to the package.

Package / Event / Date FDXE FDXG FDXC FXCC FXFR

ALL xs:date 10 Date when the scan event occurred on package.




Valid For

Data Type


Package / Event / Time FDXE FDXG FDXC FXCC FXFR

ALL xs:time 6 Time when the scan event occurred on package.

Package / Event / Type FDXE FDXG FDXC FXCC FXFR

ALL xs:string 3 The type of scan event occurred on package.

Package / Event / Description FDXE FDXG FDXC FXCC FXFR

ALL xs:string 80 The description of the scan event type occurred on package.

Package / Event / StatusExceptionCode


ALL xs:string 3

Package / Event / StatusExceptionDescription


ALL xs:string 80

PACKAGE / EVENT / ADDRESS Address to which the event occurred.

Package / Event / Address / City FDXE FDXG FDXC FXCC FXFR

ALL xs:string 40 Name of the city to which the event occurred.

Package / Event / Address / StateOrProvince Code


ALL xs:string 2 State or province to which the event occurred.




Valid For

Data Type


Package / Event / Address / PostalCode


ALL xs:string 16 Postal code of the State or province to which the event occurred. Must be numeric for U.S. No embedded dashes allowed. Valid characters: A-Z; 0-9; a-z

Package / Event / Address / CountryCode


ALL xs:string 2 Name of the country to which the event occurred.


Documents

XML TrackRequest/Response & … · FedEx Ship Manager® API XML TrackRequest/Response & TrackShipmentRequest/Response Transaction Mapping Guide June 2006