Track & Confirm API

 

 

USPS Web Tools™

Application Programming Interface

User’s Guide

Version 3.5 (11/04/2019)

 

 

 

 

 

 

 

 

 

 


 

 


Contents

1.0 Introduction to Web Tools. 5

1.1       Before you get started: 5

2.0        USPS Tracking API 5

2.1       Overview.. 5

2.2 Secure / Non-secure. 6

3.0        Track Request API 6

3.1       API Signature. 6

3.1.1        Secure. 6

3.1.2        Non-secure. 7

3.2       Request Description. 7

3.3       Response Description. 8

3.3.1        Sample Request and Response (Note: replace the userid & trackid with your values) 8

4.0        Track/Confirm Fields API 10

4.1       API Signature. 10

4.1.1        Secure. 10

4.1.2        Non-secure. 10

4.2       Request Description. 10

4.2.1        Sample Requests (Note: replace the userid & trackid with your values) 11

4.3       Response Description (Revision = 1) 14

4.3.1        Sample Response (Note: replace the userid & trackid with your values) 21

5.0        Tracking Service APIs. 23

5.1       Track and Confirm by Email API 23

5.2       API Signature. 23

5.3       Request Description. 23

5.3.1        Sample Request and Response (Note: replace the userid & trackid with your values) 25

6.0        Proof of Delivery API 26

6.1       Proof of Delivery request 26

6.2       API Signature. 26

6.3       Request Description. 26

6.3.1        Sample Requests and Response (Note: replace the userid & trackid with your values) 28

7.0        Return Receipt Electronic API 28

7.1       Return Receipt Electronic request 28

7.2       API Signature. 29

7.3       Request Description. 29

7.3.1        Sample Request and Response (Note: replace the userid & trackid with your values) 30

8.0        Track Proof of Delivery API 31

8.1       Track Proof of Delivery request 31

8.2       API Signature. 31

8.3       Request Description. 31

8.3.1        Sample Requests and Response (Note: replace the userid & trackid with your values) 33


1.0 Introduction to Web Tools

This document contains a Reference Guide to the USPS Tracking/Delivery Confirmation Label APIs. See the Developer’s Guide to learn the administrative process for gaining access to the Web Tools APIs as well as the basic mechanism for calling the APIs and processing the results. The Developer’s Guide also contains information on testing and trouble-shooting.

 

注意:The Request Parameter sections present the XML input tags for generating live requests along with the restrictions on the values allowed. An error message will be returned if an incorrect value is entered.  Also, be aware of the maximum character amounts allowed for some tags.  If the user enters more than those amounts, an error will not be generated. The Web Tool will simply pass in the characters up to the maximum amount allowed and disregard the rest.  This is important since the resulting value could prevent a correct response.

 

When building the XML request, pay particular attention to the order and case for tags. An error message will be returned if an incorrect value is entered.  Remember that all data and attribute values in this document are for illustration purposes and are to be replaced by your actual values. For instance, a line of sample code may be:

<TrackID> EJ123456780US </TrackID>

In this instance, you will replace “EJ123456780US” with the tracking ID for the package.

1.1     Before you get started:

For information on registering and getting started with Web Tools, please refer to the Step-By-Step guide found on the Technical Documentation section of the Web Tools page on usps.com/webtools.

Label API access requires extra permissions; contact the Internet Customer Care Center https://Emailus.usps.com/to request access. Indicate “Label API Access” in the subject line and explain in the body of the email:

1.            How the shipper intends to purchase and apply postage to the labels

2.            If the label image provided by the API will be modified in any way by the shipper or the software

2.0   USPS Tracking API

2.1     Overview

The Track/Confirm Web Tool lets customers determine the delivery status of their Priority Mail, Express Mail, and Package Services (Standard Post, Bound Printed Matter, Library Mail, and Media Mail) packages with Delivery Confirmation.  It will also provide tracking data right from your web site, without making your customer go to the USPS web site.  Additionally, the Track/Confirm Web Tool can be appended to your Intranet, allowing, for example, a customer service representative to answer customer queries about the status of their shipments.  The Web Tool Server returns tracking and/or delivery confirmation information for packages requested by the client.  The Track/Confirm Web Tool limits the data requested to thirty-five (35) packages per transaction.

 

:The data returned by the Track/Confirm Web Tool is intended for display only.  The content or sequence of the string data returned by the Web Tool may change.  Consequently, if you desire to apply any kind of logic against the tracking data, then you will need to use the Track/Confirm Fields Web Tool.

2.2 Secure / Non-secure

All requests can be submitted via secure HTTP, (HTTPS). The following MUST be submitted via HTTPS due to the presence of Personally Identifiable Information (PII), contained in the request.

-        Track and Confirm by Email: “PTSEmail

-        Proof of Delivery: “PTSPod

-        Return Receipt Electronic: “PTSRre

 

If these requests are sent via HTTP, the following error will be returned:

<Error>

  <Number>80040B1A</Number>

  <Description>API Authorization failure. PTSPod is not a valid API name for this protocol.     </Description>

  <Source>USPSCOM::DoAuth</Source>

</Error>

 

Only the TrackV2 requests can be sent via HTTP

3.0   Track Request API

3.1     API Signature

3.1.1   Secure

Scheme

Host

小道

API

XML

https://

stg-secure.shippingapis.com

/shippingapi.dll

?API=TrackV2

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

 

3.1.2   Non-secure

Scheme

Host

小道

API

XML

http://

stg-production.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

http://

production.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

 

注意:The “stg-production.shippingapis.com” signature host is for testing purposes. If you experience any issues connecting to this test server, please contact our helpdesk at https://Emailus.usps.com/.

3.2     Request Description

Tag Name

Occurs

描述

类型

Validation

TrackRequest

需要 

API=TrackV2

(group)

 

TrackRequest / USERID

需要

This attribute specifies your Web Tools ID. See the Developer's Guide for information on obtaining your USERID.

 

例如:

<TrackRequest USERID=”yourID”>

string

 

TrackRequest / TrackID

需要

Must be alphanumeric characters.

 

例如: 

<TrackID ID="EJ123456780US">

</TrackID>

string

minOccurs="1"

 

3.3     Response Description

Tag Name

Occurs

描述

类型

Validation

TrackResults

required once

 

(group)

 

TrackResults / RequestSeqNumber

需要

 

string

minOccurs="1"

TrackResults / ID

需要

Tracking ID

标记

 

TrackResults / TrackInfo

(group)

 

 

错误

TrackResults / TrackInfo / DeliveryNotificationDate

required once

 

string

minOccurs="0"

TrackResults / TrackInfo / ExpectedDeliveryDate

Optional

 

string

minOccurs="0"

TrackResults / TrackInfo / ExpectedDeliveryTime

Optional

 

string

minOccurs="0"

TrackResults / TrackInfo / GuaranteedDeliveryDate

Optional

 

string

minOccurs="0"

TrackResults / TrackInfo / TrackSummary

Optional

Summary of the status of the shipment, ie In-Transit, Delivered, etc.

string

示例:February 5 下午 7:28 ENROUTE 33699

TrackResults / TrackInfo / TrackDetail

optional

Scan statuses from points in transit.

string

minOccurs="0"

 

 

3.3.1   Sample Request and Response (Note: replace the userid & trackid with your values)

Test XML Request:

http://production.shippingapis.com/ShippingAPI.dll?API=TrackV2&XML=<?xml version="1.0" encoding="UTF-8" ?>

<TrackRequest USERID="xxxxxxxx">

<TrackID ID="XXXXXXXXXXX1"></TrackID>

<TrackID ID="XXXXXXXXXXX2"></TrackID>

<TrackID ID="XXXXXXXXXXX3"></TrackID>

</TrackRequest>

 

Test XML Response:

<TrackResponse>

<TrackInfo ID="XXXXXXXXXXX1">

<TrackSummary> Your item was delivered at 上午 6:50 on February 6 in BARTOW FL 33830.</TrackSummary>

<TrackDetail>February 6 上午 6:49 NOTICE LEFT BARTOW FL 33830</TrackDetail>

<TrackDetail>February 6 上午 6:48 ARRIVAL AT UNIT BARTOW FL 33830</TrackDetail>

<TrackDetail>February 6 上午 3:49 ARRIVAL AT UNIT LAKELAND FL 33805</TrackDetail>

<TrackDetail>February 5 下午 7:28 ENROUTE 33699</TrackDetail>

<TrackDetail>February 5 下午 7:18 ACCEPT OR PICKUP 33699</TrackDetail>

</TrackInfo>

<TrackInfo ID="XXXXXXXXXXX2">

<TrackSummary There is no record of that mail item. If it was mailed recently, It may not yet be tracked. 请稍后重试。</TrackSummary>

</TrackInfo>

<TrackInfo ID="XXXXXXXXXXX3">

<TrackSummary> That's not a valid number. Please check to make sure you entered it correctly.</TrackSummary>

</TrackInfo>

</TrackResponse>


 

4.0   Track/Confirm Fields API

The Track/Confirm Fields request is identical to the Track/Confirm request except for the request name and the return information.  Data returned still contains the detail and summary information, but this information is broken down into fields instead of having only one line of text.  Up to 10 tracking IDs may be contained in each request input to the Web Tool server.

4.1     API Signature

4.1.1   Secure

Scheme

Host

小道

API

XML

https://

stg-secure.shippingapis.com

/shippingapi.dll

?API=TrackV2

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

 

4.1.2   Non-secure

Scheme

Host

小道

API

XML

http://

stg-production.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

http://

production.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

 

注意:The “stg-production.shippingapis.com” signature host is for testing purposes. If you experience any issues connecting to this test server, please contact our helpdesk at https://Emailus.usps.com/

4.2     Request Description

Tag Name

Occurs

描述

类型

Validation

TrackFieldRequest

required once

API=TrackV2

(group)

 

TrackFieldRequest / USERID

需要

This attribute specifies your Web Tools ID. See the Developer's Guide for information on obtaining your USERID.

 

例如:

<TrackFieldRequest USERID=”yourID”>

string

 

TrackFieldRequest / Revision

需要

This is for versioning of the API's and for triggering response tags for future versions. In this API use a value of 1 to trigger new functionality.

 

例如: 

<Revision>1</Revision>

integer

minOccurs="0"

TrackFieldRequest / ClientIp

optional

User IP address. Required when TrackFieldRequest[Revision='1'].

 

例如:

<ClientIp>127.0.0.1</ClientIp>

string

minOccurs="0"

TrackFieldRequest / SourceId

optional

Internal User Identification.  Required when TrackFieldRequest[Revision='1'].

 

例如:

<SourceId>XYZ Corp</SourceId>

String

 

minOccurs="0"

TrackFieldRequest / SourceIdZIP

optional

ZIP Code of the requestor.

string

 

minOccurs="0"

Pattern="[0-9]{5}"

TrackFieldRequest / TrackID

需要

Package Tracking ID.  Must be alphanumeric characters.

 

例如: 

<TrackID ID="EJ123456780US">

</TrackID>

string

minOccurs="1"

TrackFieldRequest / TrackID / DestinationZipCode

optional

5 digit destination zip code.

 

例如:

<DestinationZipCode>12345</DestinationZipCode>

string

minOccurs="0"

TrackFieldRequest / TrackID / MailingDate

optional

Mailing date of package.  格式:YYYY-MM-DD

 

例如:

<MailingDate>2010-01-01</MailingDate>

string

minOccurs="0"

TrackFieldRequest

required once

 

(alias)

 

 

4.2.1   Sample Requests (Note: replace the userid & trackid with your values)

Test XML Request:

<TrackFieldRequest USERID="xxxxxxxxx">

  <ClientIp>111.0.0.1</ClientIp>

  <SourceId>MYUSPS</SourceId>

  <TrackID ID="XXXXXXXXXXX" />

</TrackFieldRequest>

Test XML Request (Revision = 1):

<TrackFieldRequest USERID="XXXXXXXXXXXXX">

  <Revision>1</Revision>

  <ClientIp>127.0.0.1</ClientIp>

  <SourceId>USPSTOOLS</SourceId>

  <TrackID ID="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"></TrackID>

</TrackFieldRequest>

Response DescriptionTag Name

Occurs

描述

类型

TrackResponse

required once

 

(group)

TrackResponse / TrackInfo

需要

 

(group)

TrackResponse / TrackInfo / ID

需要

Package Tracking ID number. 

string

TrackResponse / TrackInfo / GuaranteedDeliveryDate

optional

Guaranteed Delivery Date – Global Express Mail only:  certain countries provide a guarantee delivery.

string

TrackResponse / TrackInfo / eSOFEligible

optional

Signifies if the mail piece is eSOF eligible

Boolean

TrackResponse / TrackInfo / TrackSummary

required once

Tracking Summary Information.

(group)

TrackResponse / TrackInfo / TrackSummary / EventTime

需要

The time of the event.

string

TrackResponse / TrackInfo / TrackSummary / EventDate

需要

The date of the event.

string

TrackResponse / TrackInfo / TrackSummary / Event

需要

The event type (e.g., Enroute).

string

TrackResponse / TrackInfo / TrackSummary / EventCity

需要

The city where the event occurred.

string

TrackResponse / TrackInfo / TrackSummary / EventState

需要

The state where the event occurred.

string

TrackResponse / TrackInfo / TrackSummary / EventZIPCode

需要

The ZIP Code of the event.

string

TrackResponse / TrackInfo / TrackSummary / EventCountry

optional

The country where the event occurred.

string

TrackResponse / TrackInfo / TrackSummary / FirmName

optional

The company name if delivered to a company.

string

TrackResponse / TrackInfo / TrackSummary / Name

optional

The name of the persons signing for delivery (if available).

string

TrackResponse / TrackInfo / TrackSummary / AuthorizedAgent

optional

True/False field indicating the person signing as an Authorized Agent.

string

TrackResponse / TrackInfo / TrackSummary / EventCode

optional

The event code

string

TrackResponse / TrackInfo / TrackSummary / ActionCode

optional

The action code

string

TrackResponse / TrackInfo / TrackSummary / ReasonCode

optional

The reason code

string

TrackResponse / TrackInfo / TrackDetail

required once

Tracking Detail Information.  This group is repeatable.

(group)

TrackResponse / TrackInfo / TrackDetail / EventTime

需要

The time of the event.

string

TrackResponse / TrackInfo / TrackDetail / EventDate

需要

The date of the event.

string

TrackResponse / TrackInfo / TrackDetail / Event

需要

The event type (e.g., Enroute).

string

TrackResponse / TrackInfo /  TrackDetail / EventCity

需要

The city where the event occurred.

string

TrackResponse / TrackInfo / TrackDetail / EventState

需要

The state where the event occurred.

string

TrackResponse / TrackInfo / TrackDetail / EventZIPCode

需要

The ZIP Code of the event

string

TrackResponse / TrackInfo / TrackDetail / EventCountry

optional

The country where the event occurred.

string

TrackResponse / TrackInfo / TrackDetail / FirmName

optional

The company name if delivered to a company.

string

TrackResponse / TrackInfo / TrackDetail / Name

optional

The name of the persons signing for delivery (if available).

string

TrackResponse / TrackInfo / TrackDetail / AuthorizedAgent

optional

True/False field indicating the person signing as an Authorized Agent.

string

TrackResponse / TrackInfo / TrackDetail / EventCode

optional

The event code

string

TrackResponse / TrackInfo / TrackDetail / ActionCode

optional

The action code

string

TrackResponse / TrackInfo / TrackDetail / ReasonCode

optional

The reason code

string

TrackResponse

required once

 

(alias)

 

4.3     Response Description (Revision = 1)

Tag Name

Occurs

描述

类型

TrackResponse

required once

 

(group)

TrackResponse / TrackInfo ID

需要

Package Tracking ID number.

string

TrackResponse / TrackInfo / AdditionalInfo

optional

Additional package information

string

TrackResponse / TrackInfo / ADPScripting

optional

Additional package information

string

TrackResponse / TrackInfo / ARCHDATA

optional

Internal data availability

boolean

TrackResponse / TrackInfo / ArchiveRestoreInfo

optional

Information regarding availability of Restore service function

string

TrackResponse / TrackInfo / AssociatedLabel

optional

Associated label

String

TrackResponse / TrackInfo / CarrierRelease

optional

Indicates whether or not the mailer has authorized carrier release (T or F)

string

TrackResponse / TrackInfo / Class

optional

The class of mail. Example(s): “Priority Mail 1-Day” or “First-Class Package Service – Retail”

string

TrackResponse / TrackInfo / ClassOfMailCode

optional

Class of mail code  Examples: PM, PME, PMEI

string

TrackResponse / TrackInfo / DeliveryNotificationDate

optional

Scheduled delivery date

string

TrackResponse / TrackInfo / DestinationCity

optional

The destination city

string

TrackResponse / TrackInfo / DestinationCountryCode

optional

The destination country code

string

TrackResponse / TrackInfo / DestinationState

optional

The destination state

string

TrackResponse / TrackInfo / DestinationZip

optional

The destination zip code

string

TrackResponse / TrackInfo / EditedLabelID

Optional, only included in response for specific  SourceIDs

Identifies edited or full barcode information to support numeric only input

string

TrackResponse / TrackInfo / EmailEnabled

optional

Signifies if Track and Confirm by Email service is enabled

string

TrackResponse / TrackInfo / endofday

optional

End of Day delivery option

String

 

E=Scheduled End of Day

 

TrackResponse / TrackInfo / ExpectedDeliveryDate

optional

Expected delivery date

string

TrackResponse / TrackInfo / ExpectedDeliveryTime

optional

Expected delivery time. 示例:下午 2:00

string

TrackResponse / TrackInfo / GuaranteedDeliveryDate

optional

Guaranteed Delivery Date – Global Express Mail only:  certain countries provide a guarantee delivery. 示例:04 June 2013, 3 Business Days

string

TrackResponse / TrackInfo / GuaranteedDeliveryTime

optional

Guaranteed Delivery Time – Global Express Mail only:  certain countries provide a guarantee delivery

string

TrackResponse / TrackInfo / GuaranteedDetails

optional

Messaging to identify Guarantee limits (e.g. Loss Only Guarantee”

string

TrackResponse / TrackInfo / ItemShape

optional

Indicates the shape of the item.

EX. Letter, flat, parcel, or unknown

string

TrackResponse / TrackInfo / KahalaIndicator

optional

Indicates if the shipment

Ex. True, False

string

TrackResponse / TrackInfo / MailTypeCode

optional

The mail type code

string

TrackResponse / TrackInfo / MPDATE

optional

Internal date stamp in yyyy-mm-dd hh:mm:ss.xxxx format

string

TrackResponse / TrackInfo / MPSUFFIX

optional

Internal suffix

integer

TrackResponse / TrackInfo / OnTime

Optional

Field indicating if the item will be delivered on time as specified in the Expected or Guaranteed delivery date.

string

TrackResponse / TrackInfo / OriginCity

optional

The origin city

string

TrackResponse / TrackInfo / OriginCountryCode

optional

The origin country code

string

TrackResponse / TrackInfo / OriginState

optional

The origin state

string

TrackResponse / TrackInfo / OriginZip

optional

The origin zip code

string

TrackResponse / TrackInfo / PodEnabled

optional

Signifies if Proof of Delivery service is enabled

boolean

TrackResponse / TrackInfo / PredictiveDeliveryDate

optional

The predicted delivery date

string

TrackResponse / TrackInfo / PredictiveDeliveryTime

optional

Predicted Delivery Time

示例:3:00 PM (Or blank)

string

TrackResponse / TrackInfo / PDWStart

optional

Predicted Delivery Window start time in military format.

示例:1300

string

TrackResponse / TrackInfo / PDWEnd

optional

Predicted Delivery Window end time in military format.

示例:1500

string

TrackResponse / TrackInfo / RedeliveryEnabled

Optional

Field indicating if the item qualifies for redelivery.

string

TrackResponse / TrackInfo / RelatedRRID

optional

Related Return Receipt ID

string

TrackResponse / TrackInfo / RestoreEnabled

optional

Signifies if Restore tracking information service is enabled

boolean

TrackResponse / TrackInfo / ReturnDateNotice

Optional

Field indicating the date the item will be Returned to Sender.

string

TrackResponse / TrackInfo / RRAMenabled

optional

Signifies if RRAM service is enabled

 

boolean

TrackResponse / TrackInfo / RreEnabled

optional

Signifies if Return Receipt Electronic service is enabled

boolean

TrackResponse / TrackInfo / Service

optional, repeating up to unbounded times

Additional services purchased

string

TrackResponse / TrackInfo / ServiceTypeCode

optional

Service Type Code

string

TrackResponse / TrackInfo / Status

optional

投递状态

string

TrackResponse / TrackInfo / StatusCategory

optional

Delivery status category

 

When <EventCode>=”14”  and <Firmname> = “DPLT” Than Status Category = “Available for Agent Pickup”

string

TrackResponse / TrackInfo / StatusSummary

optional

Detailed status summary

string

TrackResponse / TrackInfo / TABLECODE

optional

Internal table code

string

TrackResponse / TrackInfo / TpodEnabled

optional

Signifies if Tracking Proof of Delivery service is enabled. True/False

boolean

TrackResponse / TrackInfo / ValueofArticle

Optional, only returned for specific  SourceIDs

Declared value of the package contents. 示例:20.00 美元

string

TrackResponse / TrackInfo/EnabledNotificationRequests / SMS / FD

optional

Mail piece eligibility for Future Delivery – Expected Delivery Date / Time Updates requests

 

Passed as a Boolean so option can be disabled if not eligible for request type

示例:True,False

boolean

TrackResponse / TrackInfo/EnabledNotificationRequests / SMS / AL

optional

Mail piece eligibility for Alert  - Delivery Exception requests

 

Passed as a Boolean so option can be disabled if not eligible for request type

示例:True,False

boolean

TrackResponse / TrackInfo / EnabledNotificationRequests / SMS / TD

optional

Mail piece eligibility for Today Delivery – Day of Delivery Update requests

 

Passed as a Boolean so option can be disabled if not eligible for request type

示例:True,False

boolean

TrackResponse / TrackInfo / EnabledNotificationRequests / SMS / UP

optional

Mail piece eligibility for UP / Mail Pickup – Available for Pickup requests

 

Passed as a Boolean so option can be disabled if not eligible for request type

示例:True,False

boolean

TrackResponse / TrackInfo / EnabledNotificationRequests / SMS / DND

optional

Mail piece eligibility for DND – Delivery Activity requests

 

Passed as a Boolean so option can be disabled if not eligible for request type

示例:True,False

boolean

TrackResponse / TrackInfo / EnabledNotificationRequests / SMS / FS

optional

Mail piece eligibility for FS– First displayable event for Informed Delivery / MyUSPS only requests

 

Passed as a Boolean so option can be disabled if not eligible for request type

示例:True,False

boolean

TrackResponse / TrackInfo / EnabledNotificationRequests / SMS / OA

optional

Mail piece eligibility for OA – In-Transit / Other Activity requests

 

Passed as a Boolean so option can be disabled if not eligible for request type

示例:True,False

boolean

TrackResponse / TrackInfo / EnabledNotificationRequests / EMAIL / FD

optional

Mail piece eligibility for Future Delivery – Expected Delivery Date / Time Updates requests

 

Passed as a Boolean so option can be disabled if not eligible for request type

示例:True,False

boolean

TrackResponse / TrackInfo / EnabledNotificationRequests / EMAIL / AL

optional

Mail piece eligibility for Alert  - Delivery Exception requests

 

Passed as a Boolean so option can be disabled if not eligible for request type

示例:True,False

boolean

TrackResponse / TrackInfo / EnabledNotificationRequests / EMAIL / TD

optional

Mail piece eligibility for Today Delivery – Day of Delivery Update requests

 

Passed as a Boolean so option can be disabled if not eligible for request type

示例:True,False

boolean

TrackResponse / TrackInfo / EnabledNotificationRequests / EMAIL / UP

optional

Mail piece eligibility for UP / Mail Pickup – Available for Pickup requests

 

Passed as a Boolean so option can be disabled if not eligible for request type

示例:True,False

boolean

TrackResponse / TrackInfo / EnabledNotificationRequests / EMAIL / DND

optional

Mail piece eligibility for DND – Delivery Activity requests

 

Passed as a Boolean so option can be disabled if not eligible for request type

示例:True,False

boolean

TrackResponse / TrackInfo / EnabledNotificationRequests / EMAIL / FS

optional

Mail piece eligibility for FS – First displayable event for Informed Delivery / MyUSPS only requests

 

Passed as a Boolean so option can be disabled if not eligible for request type

示例:True,False

boolean

TrackResponse / TrackInfo / EnabledNotificationRequests / EMAIL / OA

optional

Mail piece eligibility for OA – In-Transit / Other Activity requests

 

Passed as a Boolean so option can be disabled if not eligible for request type

示例:True,False

boolean

TrackResponse / TrackInfo / TrackSummary

optional

Tracking Summary Information.

(group)

TrackResponse / TrackInfo / TrackSummary / EventTime

optional

The time of the event.

string

TrackResponse / TrackInfo / TrackSummary / EventDate

optional

The date of the event.

string

TrackResponse / TrackInfo / TrackSummary / Event

optional

The event type (e.g., Enroute).

string

TrackResponse / TrackInfo / TrackSummary / EventCity

optional

The city where the event occurred.

string

TrackResponse / TrackInfo / TrackSummary / EventState

optional

The state where the event occurred.

string

TrackResponse / TrackInfo / TrackSummary / EventZIPCode

optional

The ZIP Code of the event.

string

TrackResponse / TrackInfo / TrackSummary / EventCountry

optional

The country where the event occurred.

string

TrackResponse / TrackInfo / TrackSummary / FirmName

optional

The company name if delivered to a company.

 

 

string

TrackResponse / TrackInfo / TrackSummary / Name

optional

The name of the persons signing for delivery (if available).

string

TrackResponse / TrackInfo / TrackSummary /  AuthorizedAgent

optional

True/False field indicating the person signing as an Authorized Agent.

boolean

TrackResponse / TrackInfo / TrackSummary /  EventCode

optional

活动编码

string

TrackResponse/ TrackInfo / TrackSummary/ TestLanguage

Optional

only included in response for specific  SourceIDs

Field indicating if test language was used

 

说明:this response tag will only display if it is True. If False, the tag will NOT display

 

boolean

TrackResponse / TrackInfo / TrackSummary /  ActionCode

optional

Action Code

string

TrackResponse / TrackInfo / TrackSummary /  ReasonCode

optional

Reason Code

string

TrackResponse / TrackInfo / TrackSummary / GeoCertified

optional

Only eligible to display with delivery (01) events. True/False

boolean

TrackResponse / TrackInfo / TrackDetail

optional

Tracking Detail Information.  This group is repeatable.

(group)

TrackResponse / TrackInfo / TrackDetail / EventTime

optional

The time of the event.

string

TrackResponse / TrackInfo / TrackDetail /  EventDate

optional

The date of the event.

string

TrackResponse / TrackInfo / TrackDetail / Event

optional

The event type (e.g., Enroute).

string

TrackResponse / TrackInfo /  TrackDetail / EventCity

optional

The city where the event occurred.

string

TrackResponse / TrackInfo /  TrackDetail / EventState

optional

The state where the event occurred.

string

TrackResponse / TrackInfo /  TrackDetail /  EventZIPCode

optional

The ZIP Code of the event

string

TrackResponse / TrackInfo /  TrackDetail / EventCountry

optional

The country where the event occurred.

string

TrackResponse / TrackInfo /  TrackDetail / FirmName

optional

The company name if delivered to a company.

string

TrackResponse / TrackInfo /  TrackDetail / Name

optional

The name of the persons signing for delivery (if available).

string

TrackResponse / TrackInfo /  TrackDetail /  AuthorizedAgent

optional

True/False field indicating the person signing as an Authorized Agent.

boolean

TrackResponse / TrackInfo /  TrackDetail /  EventCode

optional

活动编码

string

TrackResponse / TrackInfo /  TrackDetail /  ActionCode

optional

Action Code

string

TrackResponse / TrackInfo /  TrackDetail /  ReasonCode

optional

Reason Code

string

TrackResponse

需要

 

(alias)

 

4.3.1   Sample Response (Note: replace the userid & trackid with your values)

Test XML Response:

<TrackResponse>

  <TrackInfo ID="XXXXXXXXXXX">

    <TrackSummary>

      <EventTime>下午 10:45</EventTime>

      <EventDate>January 6, 2016</EventDate>

      <Event>Arrived at USPS Facility</Event>

      <EventCity>COLUMBUS</EventCity>

      <EventState>OH</EventState>

      <EventZIPCode>43218</EventZIPCode>

      <EventCountry></EventCountry>

      <FirmName></FirmName>

      <Name></Name>

      <AuthorizedAgent>false</AuthorizedAgent>

    </TrackSummary>

    <TrackDetail>

      <EventTime>上午 9:10</EventTime>

      <EventDate>January 6, 2016</EventDate>

      <Event>接收</Event>

      <EventCity>LAKE CHARLES</EventCity>

      <EventState>IL</EventState>

      <EventZIPCode>12345</EventZIPCode>

      <EventCountry></EventCountry>

      <FirmName></FirmName>

      <Name></Name>

      <AuthorizedAgent>false</AuthorizedAgent>

    </TrackDetail>

  </TrackInfo>

</TrackResponse>

 

Test XML Response(Revision = 1):

<TrackResponse>

  <TrackInfo ID="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX">

    <CarrierRelease>false</CarrierRelease>

    <Class>Priority Mail Express&lt;SUP&gt;&amp;reg;&lt;/SUP&gt;</Class>

    <ClassOfMailCode>EX</ClassOfMailCode>

    <DestinationCity>BIRMINGHAM</DestinationCity>

    <DestinationState>AL</DestinationState>

    <DestinationZip>35212</DestinationZip>

    <EmailEnabled>true</EmailEnabled>

    <EnabledNotificationRequests>

      <SMS>

        <FD>正确</FD>

        <AL>正确</AL>

        <TD>正确</TD>

        <UP>正确</UP>

        <DND>正确</DND>

        <OA>正确</OA>

      </SMS>

      <Email>

        <FD>正确</FD>

        <AL>正确</AL>

        <TD>正确</TD>

        <UP>正确</UP>

        <DND>正确</DND>

        <OA>正确</OA>

      </Email>

    </EnabledNotificationRequests>

    <ItemShape>unknown</ItemShape>

    <KahalaIndicator>false</KahalaIndicator>

    <MailTypeCode>DM</MailTypeCode>

    <MPDATE>2019-08-21 10:44:08.000000</MPDATE>

    <MPSUFFIX>999999999</MPSUFFIX>

    <OnTime>false</OnTime>

    <PodEnabled>true</PodEnabled>

    <TPodEnabled>false</TPodEnabled>

    <RedeliveryEnabled>false</RedeliveryEnabled>

    <RestoreEnabled>false</RestoreEnabled>

    <RramEnabled>false</RramEnabled>

    <RreEnabled>false</RreEnabled>

    <Service>邮局至收件人</Service>

    <Service>包含高达 100 美元的保险</Service>

    <ServiceTypeCode>701</ServiceTypeCode>

    <Status>CMC1496 SIT testing - Delivered</Status>

    <StatusCategory>CMC1496 - SIT - Delivered</StatusCategory>

    <StatusSummary>CMC1496 SIT testing - Your item was delivered at 上午 7:30 on August 21, 2019 in BIRMINGHAM, AL 35212.StatusSummary>

    <TABLECODE>T</TABLECODE>

    <TrackSummary>

      <EventTime>上午 7:30</EventTime>

      <EventDate>August 21, 2019</EventDate>

      <Event>CMC1496 SIT testing - Delivered</Event>

      <EventCity>BIRMINGHAM</EventCity>

      <EventState>AL</EventState>

      <EventZIPCode>35212</EventZIPCode>

      <EventCountry></EventCountry>

      <FirmName></FirmName>

      <Name></Name>

      <AuthorizedAgent>false</AuthorizedAgent>

      <EventCode>01</EventCode>

      <EventStatusCategory>CMC1496 - SIT - Delivered</EventStatusCategory>

    </TrackSummary>

  </TrackInfo>

</TrackResponse>

5.0  Tracking Service APIs

Four service APIs are offered in conjunction with “Revision = 1” of the Track/Confirm Fields Web Tool: Track and Confirm by Email, Proof of Delivery, Return Receipt Electronic and Restore for tracking information.  The response data from Track/Confirm Fields request determines which services are available for a tracking ID.  Each request input to the Web Tool server for the tracking service APIs is limited to 1 tracking ID. 

These APIs are restricted to USPS internal use only.

5.1     Track and Confirm by Email API

The Track and Confirm by Email API allows the customer to submit their email address to be notified of current or future tracking activity.

The table below presents the XML input tags for generating Live requests and the restrictions on the values allowed.  An error message will be returned if an incorrect value is entered.  Also, be aware of the maximum character amounts allowed for some tags.  If the user enters more than those amounts, an error will not be generated.  The Web Tool will simply pass in the characters up to the maximum amount allowed and disregard the rest.  This is important since the resulting value could prevent a correct response.

When building the XML request, pay particular attention to the order and case for tags.  An error message will be returned if an incorrect value is entered.  Remember that all data and attribute values in this document are for illustration purposes and are to be replaced by your actual values.  For instance, a line of sample code may be:

<TrackID> EJ123456780US </TrackID>

In this instance, you will replace “EJ123456780US” with the tracking ID for the package.

5.2     API Signature

Scheme

Host

小道

API

XML

https://

stg-secure.shippingapis.com

/shippingapi.dll

?API=PTSEmail

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=PTSEmail

&XML=(see below)

备注

The “stg-secure.shippingapis.com” signature host is for testing purposes. If you experience any issues connecting to this test server, please contact our helpdesk at https://Emailus.usps.com/

注意:This API requires escalation to our helpdesk to request access please reference https://Emailus.usps.com/.

5.3     Request Description

Tag Name

Occurs

描述

类型

Validation

PTSEmailRequest

required once

API=PTSEmail

(group)

 

PTSEmailRequest / USERID

需要

This attribute specifies your Web Tools ID. See the Developer's Guide for information on obtaining your USERID.

string

minOccurs="1"

PTSEmailRequest / TrackId

需要

Must be alphanumeric characters.

例如: 

<TrackId>EJ123456780US</TrackId>

string

minOccurs="1"

PTSEmailRequest / ClientIp

optional

User IP address. 

 

例如:

<ClientIp>127.0.0.1</ClientIp>

string

minOccurs="0"

PTSEmailRequest / SourceId

Optional

Internal User Identification. 

 

例如:

<SourceId>XYZ Corp</SourceId>

string

minOccurs="0"

PTSEmailRequest / MpSuffix

需要

MPSUFFIX value located in Track/Confirm Fields API response data. Unique to each TrackID.

例如:<MpSuffix>9402</MpSuffix>

integer

minOccurs="1"

PTSEmailRequest / MpDate

需要

MPDATE value located in Track/Confirm Fields API response data. Unique to each TrackId.

例如:

<MpDate>2009-07-02 00:42:23.35744</MpDate>

string

minOccurs="1"

PTSEmailRequest / RequestType

required once

repeating up to 5 times

Enter a notification request type from the choices available.

“AL”  E-Mail Alert

 

“FD”  E-Mail Future Delivery

 

“ED”  E-Mail Delivery/Non Delivery activity

 

“TD”  E-Mail Today Delivery

 

“UP” E-Mail Available for Pickup

 

“FS” Package addressed to me/myusps only

 

“OA” Other Activity

例如:

<RequestType>ED</RequestType>

string

minOccurs="1"

maxOccurs =”7”

 

Enumerations no longer valid:

 EC, EN, EB

Enumerations:

      AL

      FD

      ED

      TD

      UP

      FS

      OA

PTSEmailRequest / FirstName

optional

Recipient First Name.

 

例如:<FirstName>John</FirstName>

string

 

minOccurs="0"

PTSEmailRequest / LastName

optional

Recipient Last Name.

 

例如:<LastName>Doe</LastName>

string

 

minOccurs="0"

PTSEmailRequest / Email1

required once

Complete valid e-mail address is required if tag is used.

 

例如:<Email1>cpapple@email.com</Email1>

string

minOccurs="1"

PTSEmailRequest / Email2

optional

Complete valid e-mail address is required if tag is used.

string

minOccurs="0"

PTSEmailRequest / Email3

optional

Complete valid e-mail address is required if tag is used.

string

minOccurs="0"

PTSEmailRequest

required once

API=PTSEmail

(alias)

 

5.3.1   Sample Request and Response (Note: replace the userid & trackid with your values)

Test XML Request:

<PTSEmailRequest USERID="xxx">

    <TrackId>XXXXXXXXXXX</TrackId >

    <ClientIp>127.0.0.1</ClientIp>

    <SourceId>XYZ Corp</SourceId>

    <MpSuffix >9402</MpSuffix>

    <MpDate >2009-07-02 00:42:23.35744</MpDate>

    <RequestType>EN</RequestType>

    <FirstName>John</FirstName>

    <LastName >Doe</LastName>

    <Email1>cpapple@email.com</Email1>

    <Email2></Email2>

    <Email3></Email3>

</PTSEmailRequest>

 

Test XML Response:

<PTSEMAILRESULT>

    <ResultText>Your request for all activity to-date will be processed within four hours. Any future activity   will be processed whenever there is new delivery related event activity.</ResultText>

    <ReturnCode>0</ReturnCode>

</PTSEMAILRESULT>

 

Test XML Request: Multiple Requests.

<PTSEmailRequest USERID="xxx">

    <TrackId>XXXXXXXXXX1</TrackId >

    <ClientIp>127.0.0.1</ClientIp>

    <MpSuffix >9402</MpSuffix>

    <MpDate >2009-07-02 00:42:23.35744</MpDate>

    <RequestType >AL</RequestType>

    <RequestType >FD</RequestType>

    <RequestType >UP</RequestType>

    <FirstName >John</FirstName>

    <LastName >Doe</LastName>

    <Email1> cpapple@email.com </Email1>

    <Email2></Email2>

    <Email3></Email3>

</PTSEmailRequest>

6.0   Proof of Delivery API

Proof of Delivery is a letter that includes the recipient's name and a copy of their signature.  The Proof of Delivery API allows the customer to request proof of delivery notification via email. 

6.1     Proof of Delivery request

The table below presents the XML input tags for generating Live requests and the restrictions on the values allowed.  An error message will be returned if an incorrect value is entered.  Also, be aware of the maximum character amounts allowed for some tags.  If the user enters more than those amounts, an error will not be generated.  The Web Tool will simply pass in the characters up to the maximum amount allowed and disregard the rest.  This is important since the resulting value could prevent a correct response.

When building the XML request, pay particular attention to the order and case for tags.  An error message will be returned if an incorrect value is entered.  Remember that all data and attribute values in this document are for illustration purposes and are to be replaced by your actual values.  For instance, a line of sample code may be:

<TrackID> EJ123456780US </TrackID>

 

In this instance, you will replace “EJ123456780US” with the tracking ID for the package.

6.2     API Signature

Scheme

Host

小道

API

XML

https://

stg-secure.shippingapis.com

/shippingapi.dll

?API=PTSPod

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=PTSPod

&XML=(see below)

备注

The “stg-secure.shippingapis.com” signature host is for testing purposes. If you experience any issues connecting to this test server, please contact our helpdesk at https://Emailus.usps.com/.

注意:This API requires escalation to our helpdesk to request access please reference https://Emailus.usps.com/.  

 

6.3     Request Description

Tag Name

Occurs

描述

类型

Validation

PTSPodRequest

required once

 

(group)

 

PTSPodRequest / USERID

需要

This attribute specifies your Web Tools ID. See the Developer's Guide for information on obtaining your USERID.

string

minOccurs="1"

PTSPodRequest / TrackId

需要

Must be alphanumeric characters.

例如: 

<TrackId>EJ123456780US</TrackId>

string

minOccurs="1"

PTSPodRequest / ClientIp

optional

User IP address. 

 

例如:

<ClientIp>127.0.0.1</ClientIp>

string

minOccurs="0"

PTSPodRequest / SourceId

optional

Internal User Identification. 

 

例如:

<SourceId>XYZ Corp</SourceId>

string

minOccurs="0"

PTSPodRequest / MpSuffix

需要

MPSUFFIX value located in Track/Confirm Fields API response data. Unique to each TrackId.

例如:<MpSuffix>9402</MpSuffix>

integer

minOccurs="1"

PTSPodRequest / MpDate

需要

MPDATE value located in Track/Confirm Fields API response data. Unique to each TrackID.

例如:

<MpDate>2009-07-02 00:42:23.35744</MpDate>

string

minOccurs="1"

PTSPodRequest / RequestType

需要

Enter a notification request type from the choices available.

 

例如:

<RequestType>Email</RequestType>

string

minOccurs="1"

PTSPodRequest / FirstName

需要 

Recipient First Name.

 

例如:<FirstName>John</FirstName>

string

minOccurs="1"

PTSPodRequest / LastName

需要

Recipient Last Name.

 

例如:<LastName>Doe</LastName>

string

minOccurs="1"

PTSPodRequest / Email1

optional

Required when PTSPodRequest[RequestType=’Email’]

 

Complete valid e-mail address is required if tag is used.

 

例如:<Email1>cpapple@email.com</Email1>

string

minOccurs="0"

PTSPodRequest / Email2

optional

Complete valid e-mail address is required if tag is used.

string

minOccurs="0"

PTSPodRequest / Email3

optional

Complete valid e-mail address is required if tag is used.

string

minOccurs="0"

PTSPodRequest / FaxNumber

optional

传真号码

string

minOccurs="0"

PTSPodRequest / AddressLine1

optional

地址行 1

string

minOccurs="0"

PTSPodRequest / AddressLine2

optional

地址行 2

string

minOccurs="0"

PTSPodRequest / City

optional

城市

string

minOccurs="0"

PTSPodRequest / State

optional

string

minOccurs="0"

PTSPodRequest / Zip

optional

邮政编码

string

minOccurs="0"

PTSPodRequest / VerifyAddress

optional

 

boolean

minOccurs="0"

PTSPodRequest / TableCode

需要

TableCode value located in Track/Confirm Fields API response data. Unique to each TrackID.

例如:

<TableCode>T</TableCode>

string

minOccurs="1"

PTSPodRequest / CustRegID

optional

Unique 10-byte numeric value that’s associated to each user

String

minOccurs="0"

6.3.1   Sample Requests and Response (Note: replace the userid & trackid with your values)

Test XML Request:

<PTSPodRequest USERID="xxx">

    <TrackId>XXXXXXXXXXX</TrackId >

    <ClientIp>127.0.0.1</ClientIp>

    <SourceId>IVR</SourceId>

    <MpSuffix>9402</MpSuffix>

    <MpDate>2009-07-02 00:42:23.35744</MpDate>

    <RequestType>Email</RequestType>

    <FirstName>John</FirstName>

    <LastName>Doe</LastName>

    <Email1>cpapple@email.com </Email1>

    <Email2></Email2>

    <Email3></Email3>

    <TableCode>T</TableCode>

    <CustRegID>1234567890</CustRegID>

</PTSPodRequest>

 

Test XML Response:

<PTSPODRESULT>

    <ResultText>Your Proof of Delivery record is complete and will be processed shortly.</ResultText>

    <ReturnCode>0</ReturnCode>

</PTSPODRESULT>