国内邮件

服务

标准

 

USPS Web Tools™

Application Programming Interface

用户指南

Version 3.5 (08/07/2023)

 

 

 


 

目录

1.0        Introduction to Web Tools. 3

1.1        Before you get started: 3

2.0        Priority Mail Service Standards API 3

2.1        Overview. 3

2.1.1        API Signature Table. 3

2.2        Request Descriptions. 3

2.2.1        Sample Request 4

2.3        Response Descriptions. 5

2.3.1        Sample Response. 5

3.0        Package Services “StandardB” API 5

3.1        Overview. 5

3.1.1        API Signature Table. 6

3.2        Request Descriptions. 6

3.2.1        Sample Request 7

3.3        Response Descriptions. 7

3.3.1        Sample Response. 7

4.0        First Class Mail Service Standards API 8

4.1        Overview. 8

4.1.1        API Signature Table. 8

4.2        Request Descriptions. 8

4.2.1        Sample Request 9

4.3        Response Descriptions. 9

4.3.1        Sample Response. 10

5.0        Express Mail Service Commitments API 10

5.1        Overview. 10

5.1.1        API Signature Table. 10

5.2        Request Descriptions. 10

5.2.1        Sample Request 11

5.3        Response Descriptions. 11

5.3.1        Sample Request 13


1.0   Introduction to Web Tools

This document contains a Reference Guide to the Package Service Standards APIs. See the Developers 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 troubleshooting.

注意: 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. Web Tools 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:

<DestinationZIP>12345</DestinationZIP>

In this instance, you will replace “12345” with the destination Zip Code for your request.

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 Web Tools Technical Documentation Page.

 

2.0        Priority Mail Service Standards API

2.1         Overview

The Priority Mail Service Standards API receives requests and returns the number of days (on average) it will take a Priority Mail package to arrive at its destination. Ensure that end-users understand that these are service standards and not guaranteed commitments. The Priority Mail Service Standards API processes a single request.

2.1.1   API Signature Table

Scheme

Host

小道

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=PriorityMail

&XML=(see below)

 

2.2         Request Descriptions

Tag Name

Occurs

描述

类型

Validation

PriorityMailRequest

需要 

 

(Alias)

 

PriorityMailRequest / USERID

需要

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

例如:USERID="XXXXXXX"

NMTOKEN

 

PriorityMailRequest / PASSWORD

Optional

This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password.

例如:PASSWORD="XXXXXXX"

NMTOKEN

 

PriorityMailRequest / OriginZip

需要

Origination and destination Zip Codes must be valid. Either the first 3 digits or first 5 digits of the Zip Code are entered between the open tag and close tag. 

例如:

<OriginZip>90210</OriginZip>

String

 

PriorityMailRequest / DestinationZip

需要

Origination and destination Zip Codes must be valid and must be 5 digits.

例如: <DestinationZip>20770</DestinationZip>

String

 

PriorityMailRequest / DestinationType

Optional

Destination Type for package. 

Valid Values:

“1” = PO-Addressee – Street (Default Value)

“2” = PO-Addressee – PO Box

“3” = Hold For Pick-up

例如:<DestinationType>1</DestinationType>

String

Enumeration

·        1

·        2

·        3

PriorityMailRequest / PMGuarantee

Optional

Default “N”

Boolean

 

PriorityMailRequest / MailClass

需要

Defines mail class for commitment data.

Mail Class Value

描述

2

Priority Mail

201

Priority Mail 1-Day (Deprecated)

202

Priority Mail 2-Day (Deprecated)

203

Priority Mail 3-Day (Deprecated)

204

Priority Mail Military

205

Priority Mail DPO

206

Priority Mail Offshore

例如:

<MailClass>0<MailClass>

 

注意: When <MailClass>=”201, 202, or 203”, 1-Day, 2-Day and/or 3-Day references will be removed from response data and a single XML response for Priority Mail service standards will return.

String

minOccurs="1" maxOccurs="1"

Enumeration

·        2

·        201

·        202

·        203

·        204

·        205

·        206

PriorityMailRequest

Required once

 

(Alias)

 

2.2.1   Sample Request

Request: PriorityMail:

<PriorityMailRequest USERID="XXXXXXXXX" PASSWORD="">

<OriginZip>90201</OriginZip>

<DestinationZip>21114</DestinationZip>

<MailClass>201</MailClass>

</PriorityMailRequest>

2.3         Response Descriptions

Tag Name

Occurs

描述

类型

Validation

PriorityMailResponse

需要

 

(Alias)

 

PriorityMailResponse / OriginZip

需要

OriginationZip sent in request.

String

 

PriorityMailResponse / DestinationZip

需要

DestinationZip sent in request.

String

 

PriorityMailResponse / Days

Optional

Numbers of days expected to deliver.

String

 

PriorityMailResponse / IsGuaranteed

Optional

Is the delivery guaranteed.

String

 

PriorityMailResponse / Message

Optional

Service Standards Messaging. Appears when applicable.

 

For example:<Msg>Your shipment may be delayed due to transportation issues.</Msg>

String

 

PriorityMailResponse / EffectiveAcceptanceDate

Optional

Effective Acceptance Date is returned when <DestinationType> is specified in the request.

String

 

PriorityMailResponse / ScheduledDeliveryDate

Optional

Scheduled Delivery Date is returned when <DestinationType> is specified in the request.

String

 

PriorityMailResponse

需要

 

(Alias)

 

2.3.1     Sample Response

《response: PriorityMail

<PriorityMailResponse>

<OriginZip>20024</OriginZip>

<DestinationZip>20770</DestinationZip>

<Days>1</Days>

<EffectiveAcceptanceDate>2021-09-16</EffectiveAcceptanceDate>

<ScheduledDeliveryDate>2021-09-17</ScheduledDeliveryDate>

</PriorityMailResponse>

3.0        Package Services “StandardB” API

3.1         Overview

The Package Services “StandardB” API receives requests and returns the average number of days it will take a package to arrive at its destination. There are four types of Package Services: Standard Post, Bound Printed Matter, Library Mail, and Media Mail. The Package Services “StandardB” API processes a single request. Ensure that end-users understand that these are service standards and not guaranteed commitments.

3.1.1     API Signature Table

Scheme

Host

小道

API

XML

https://

secure.shippingapis.com/

shippingapi.dll?

API=StandardB

&XML=(see below)

3.2         Request Descriptions

Tag Name

Occurs

描述

类型

Validation

StandardBRequest

需要 

 

(Alias)

 

StandardBRequest / USERID

需要

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

例如:USERID="XXXXXXX"

NMTOKEN

 

StandardBRequest / PASSWORD

Optional

This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password.

例如:PASSWORD="XXXXXXX"

NMTOKEN

 

StandardBRequest / OriginZip

需要

Origination and destination Zip Codes must be valid. Either the first 3 digits or first 5 digits of the Zip Code are entered between the open tag and close tag. 

例如:

<OriginZip>90210</OriginZip>

String

 

StandardBRequest / DestinationZip

需要

Origination and destination Zip Codes must be valid and must be 5 digits.

例如:

<DestinationZip>20770</DestinationZip>

String

 

StandardBRequest / DestinationType

Optional

Destination Type for package. 

Valid Values:

“1” = PO-Addressee – Street (Default Value)

“2” = PO-Addressee – PO Box

“3” = Hold For Pick-up

例如: <DestinationType>1</DestinationType>

String

Enumeration

·        1

·        2

·        3

StandardBRequest / MailClass

需要

Defines mail class for commitment data.

Mail Class Value

描述

6

包裹服务

601

Parcel Select (Deprecated)

602

标准邮寄

603

Media Mail(媒体邮件)

604

图书馆邮件

605

装订的印刷材料

例如:

<MailClass>0<MailClass>

String

minOccurs="1" maxOccurs="1"

Enumeration

·        6

·        601

·        602

·        603

·        604

·        605

StandardBRequest

需要

 

(Alias)

 

3.2.1     Sample Request

Test XML Request:

<StandardBRequest USERID="XXXXXXXXX" PASSWORD="">

<OriginZip>90201</OriginZip>

<DestinationZip>21114</DestinationZip>

<MailClass>601</MailClass>

</StandardBRequest>

3.3         Response Descriptions

Tag Name

Occurs

描述

类型

Validation

StandardBResponse

需要

 

(Alias)

 

StandardBResponse / OriginZip

需要

OriginationZip sent in request.

 

String

 

StandardBResponse / DestinationZip

需要

DestinationZip sent in request.

 

String

 

StandardBResponse / Days

Optional

Numbers of days expected to deliver.

 

String

 

StandardBResponse / Message

Optional

Service Standards Messaging. Appears when applicable.

 

For example:<Msg>Your shipment may be delayed due to transportation issues.</Msg>

String

 

StandardBResponse / EffectiveAcceptanceDate

Optional

Effective Acceptance Date is returned when <DestinationType> is specified in the request.

String

 

StandardBResponse / ScheduledDeliveryDate

Optional

Scheduled Delivery Date is returned when <DestinationType> is specified in the request.

String

 

StandardBResponse

需要

 

(Alias)

 

3.3.1     Sample Response

Test XML Response:

<StandardBResponse>

<OriginZip>90201</OriginZip>

<DestinationZip>21114</DestinationZip>

<Days>7</Days>

<EffectiveAcceptanceDate>2021-09-16</EffectiveAcceptanceDate>

<ScheduledDeliveryDate>2021-09-23</ScheduledDeliveryDate>

</StandardBResponse>

 

4.0        First Class Mail Service Standards API

4.1         Overview

The First Class Mail Service Standards API receives requests and returns the average number of days it will take a package to arrive at its destination. The First Class Mail Service Standards API processes a single request. Ensure that end-users understand that these are service standards and not guaranteed commitments. 说明:Effective July 9th, 2023, First-Class Package Service was replaced with Ground Advantage. The First Class Mail Service Standards API supports First-Class Mail flats and Ground Advantage parcels.

4.1.1     API Signature Table

Scheme

Host

小道

API

XML

https://

secure.shippingapis.com/

shippingapi.dll?

API=FirstClassMail

&XML=(see below)

4.2         Request Descriptions

Tag Name

Occurs

描述

类型

Validation

FirstClassMailRequest

需要 

 

(Alias)

 

FirstClassMailRequest / USERID

需要

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

例如:USERID="XXXXXXX"

NMTOKEN

 

FirstClassMailRequest / PASSWORD

Optional

This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password.

例如:PASSWORD="XXXXXXX"

NMTOKEN

 

FirstClassMailRequest / OriginZip

需要

Origination and destination Zip Codes must be valid. Either the first 3 digits or first 5 digits of the Zip Code are entered between the open tag and close tag. 

例如:

<OriginZip>90210</OriginZip>

String

 

FirstClassMailRequest / DestinationZip

需要

Origination and destination Zip Codes must be valid and must be 5 digits.

例如:

<DestinationZip>20770</DestinationZip>

String

 

FirstClassMailRequest / DestinationType

Optional

Destination Type for package. 

1 = PO-Addressee – Street (Default)

2 = PO-Addressee – PO Box

3 = Hold For Pick-up

例如:

<DestinationType>1</DestinationType>

String

Enumeration

·        1

·        2

·        3

FirstClassMailRequest / MailClass

需要

Defines mail class for commitment data.

Mail Class Value

描述

3

USPS Ground Advantage (up to 15.999 oz)

301

First-Class Mail 信件

302

First-Class Mail Flats

303

First-Class Mail Cards

304

USPS Ground Advantage (up to 15.999 oz)

 

例如:

<MailClass>0<MailClass>

String

minOccurs="1" maxOccurs="1"

Enumeration

·        3

·        301

·        302

·        303

·        304

FirstClassMailRequest

Required once

 

(Alias)

 

4.2.1     Sample Request

Request: FirstClassMail

<FirstClassMailRequest USERID="XXXXXXXXX" PASSWORD="">

<OriginZip>90201</OriginZip>

<DestinationZip>21114</DestinationZip>

<MailClass>301</MailClass>

</FirstClassMailRequest>

4.3         Response Descriptions

Tag Name

Occurs

描述

类型

Validation

FirstClassMailResponse

需要

 

(Alias)

 

FirstClassMailResponse / OriginZip

需要

OriginationZip sent in request.

String

 

FirstClassMailResponse / DestinationZip

需要

DestinationZip sent in request.

String

 

FirstClassMailResponse / Days

Optional

Numbers of days expected to deliver.

String

 

FirstClassMailResponse / Message

Optional

Service Standards Messaging. Appears when applicable.

 

For example:<Msg>Your shipment may be delayed due to transportation issues.</Msg>

String

 

FirstClassMailResponse / EffectiveAcceptanceDate

Optional

Effective Acceptance Date is returned when <DestinationType> is specified in the request.

String

 

FirstClassMailResponse / ScheduledDeliveryDate

Optional

Scheduled Delivery Date is returned when <DestinationType> is specified in the request.

String

 

FirstClassMailResponse

需要

 

(Alias)

 

4.3.1     Sample Response

Response FirstClassMail:

<FirstClassMailResponse>

<OriginZip>90201</OriginZip>

<DestinationZip>21114</DestinationZip>

<Days>3</Days>

<EffectiveAcceptanceDate>2021-09-16</EffectiveAcceptanceDate>

<ScheduledDeliveryDate>2021-09-19</ScheduledDeliveryDate>

</FirstClassMailResponse>

 

5.0        Express Mail Service Commitments API

5.1         Overview

The Express Mail Service Commitments API provides delivery commitments for Express Mail packages for the given Zip Codes to include package drop-off information. A user provides an origination and a destination Zip Code and an optional current or future date that the package will be shipped.

5.1.1     API Signature Table

Scheme

Host

小道

API

XML

https://

secure.shippingapis.com/

shippingapi.dll?

API=ExpressMailCommitment

&XML=(see below)

5.2         Request Descriptions

Tag Name

Occurs

描述

类型

Validation

ExpressMailCommitmentRequest

需要 

 

(Alias)

 

ExpressMailCommitmentRequest / USERID

需要

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

例如:USERID="XXXXXXX"

NMTOKEN

 

ExpressMailCommitmentRequest / PASSWORD

Optional

This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password.

例如:PASSWORD="XXXXXXX"

NMTOKEN

 

ExpressMailCommitmentRequest / OriginZIP

需要

5 Digit Zip Code of the package destination. 

例如:

<OriginZIP>90210</OriginZIP>

String

 

ExpressMailCommitmentRequest / DestinationZIP

需要

Origination and destination Zip Codes must be valid and must be 5 digits.

例如:

<DestinationZIP>20770</DestinationZIP>

String

 

ExpressMailCommitmentRequest / Date

需要

Date package is shipped. Can be left blank. Can use formats MM/DD/YYYY or DD-MMM-YYYY.

例如:

<Date>05-May-2014</Date>

String

 

ExpressMailCommitmentRequest / DropOffTime

Optional

Time package is shipped. This tag can be omitted or left blank. Use format HH:MM such as 13:30.

例如:

<DropOffTime>15:00</ DropOffTime >

String

 

ExpressMailCommitmentRequest / ReturnDates

Optional

Indicates if Scheduled Delivery and Effective Acceptance dates should be returned. Specify ‘true’ or ‘false’.

例如:

<ReturnDates>正确</ReturnDates>

String

 

ExpressMailCommitmentRequest / PMGuarantee

Optional

Indicator to display Guarantee information for applicable service types.

 “Y” = Yes, display

“N” = No, do not display (Default Value)

String

Enumeration

·        Y

·        N

ExpressMailCommitmentRequest

需要

 

(Alias)

 

5.2.1     Sample Request

Request: ExpressMailCommitment

<ExpressMailCommitmentRequest USERID="XXXXXXXXX" PASSWORD="">

<OriginZIP>63123</OriginZIP>

<DestinationZIP>89301</DestinationZIP>

<Date>05-26-2021</Date>

<DropOffTime>09:00</DropOffTime>

<ReturnDates>正确</ReturnDates>

<PMGuarantee>Y</PMGuarantee>

</ExpressMailCommitmentRequest>

 

5.3         Response Descriptions

Tag Name

Occurs

描述

类型

Validation

ExpressMailCommitmentResponse

需要 

 

(Alias)

 

ExpressMailCommitmentResponse / OriginZIP

需要

OriginationZip sent in request.

String

 

ExpressMailCommitmentResponse / OriginCity

需要

Originating City.

String

 

ExpressMailCommitmentResponse / OriginState

需要

Originating State.

String

 

ExpressMailCommitmentResponse / DestinationZIP

需要

DestinationZip sent in request.

String

 

ExpressMailCommitmentResponse / DestinationCity

需要

Destinating City.

String

 

ExpressMailCommitmentResponse / DestinationState

需要

Destinating State.

String

 

ExpressMailCommitmentResponse / Date

需要

Date package shipped.

String

 

ExpressMailCommitmentResponse / Time

需要

Time.

String

 

ExpressMailCommitmentResponse / ExpeditedTransMessage

Optional

Expedited Transportation Message. Returned when applicable and the request has the ReturnDates set to true.

String

 

ExpressMailCommitmentResponse / MsgCode

Optional

Message Code. Returned when applicable and the request has the ReturnDates set to true.

 

Valid Message Code

“TM103” = Your shipment may be delayed due to transportation issues.

String

Enumeration=

·        TM103

ExpressMailCommitmentResponse / Msg

Optional

Message Text. Returned when applicable and the request has the ReturnDates set to true.

 

For example:<Msg>Your shipment may be delayed due to transportation issues.</Msg>

String

 

ExpressMailCommitmentResponse / EffectiveAcceptanceDate

Optional

Effective Acceptance Date. Returned when the request has the ReturnDates set to true.

String

 

ExpressMailCommitmentResponse / Commitment

Optional

Holds the details of a commitment. Returned if valid.

(Group)

 

ExpressMailCommitmentResponse / Commitment / Name

Optional

Commitment Name

String

Enumeration=

·        1-Day

·        2-Day

·        3-Day

·        DPO

·        Military

ExpressMailCommitmentResponse / Commitment / Time

Optional

Commitment Time. (eg: 6:00 PM)

String

 

ExpressMailCommitmentResponse / Commitment / Sequence

Optional

Commitment Sequence

Seq #  

Service Standard

A0118

1-Day at 6:00 PM

B0118

1-Day at 6:00 PM

A0218

2-Day at 6:00 PM

B0218

2-Day at 6:00 PM

String

Enumeration=

·        A0118

·        B0118

·        A0218

·        B0218

ExpressMailCommitmentResponse / Commitment / Location

Optional

Groups drop off location information.

(Group)

 

ExpressMailCommitmentResponse / Commitment / Location / ScheduledDeliveryDate

Optional

预定投递日期。Returned when the request has the ReturnDates set to true.

String

 

ExpressMailCommitmentResponse / Commitment / Location / CutOff

Optional

Cut-Off Time.

String

 

ExpressMailCommitmentResponse / Commitment / Location / Facility

Optional

Facility Type

String

Enumeration=

·        POST OFFICE

·        PRIORITY MAIL EXPRESS COLLECTION BOX

·        AIR MAIL FACILITY

ExpressMailCommitmentResponse / Commitment / Location / Street

Optional

Facility Street

String

 

ExpressMailCommitmentResponse / Commitment / Location / City

Optional

Facility City

String

 

ExpressMailCommitmentResponse / Commitment / Location / State

Optional

Facility State

String

 

ExpressMailCommitmentResponse / Commitment / Location / Zip

Optional

Facility Zip Code

String

 

ExpressMailCommitmentResponse / Commitment / Location /  IsGuaranteed

Optional

Indicates if Guaranee is offered. Will only be returned if the PMGuarantee in the request is set to “Y”.

1 = Guaranteed

2 = No Guarantee

3 = Temporary No Guarantee

String

Enumeration=

·        1

·        2

·        3

ExpressMailCommitmentResponse / Message

Optional

Message indicating over 200 location, when there are more than the 200 returned.

String

 

ExpressMailCommitmentResponse

需要 

 

(Alias)

 

5.3.1     Sample Request

《response: ExpressMailCommitment

<ExpressMailCommitmentResponse>

<OriginZIP>63123</OriginZIP>

<OriginCity>SAINT LOUIS</OriginCity>

<OriginState>MO</OriginState>

<DestinationZIP>89301</DestinationZIP>

<DestinationCity>ELY</DestinationCity>

<DestinationState>NV</DestinationState>

<Date>26-May-2021</Date>

<Time>9:00AM</Time>

<EffectiveAcceptanceDate>2021-05-26</EffectiveAcceptanceDate>

<Commitment>

<CommitmentName>2-Day</CommitmentName>

下午 <CommitmentTime>6:00</CommitmentTime>

<CommitmentSequence>A0218</CommitmentSequence>

<Location>

<ScheduledDeliveryDate>2021-05-28</ScheduledDeliveryDate>

下午 <CutOff>5:30</CutOff>

<Facility>邮局</Facility>

<Street>55 GRASSO PLZ</Street>

<City>SAINT LOUIS</City>

<State>MO</State>

<Zip>63123</Zip>

</Location>

</Commitment>

<Commitment>

<CommitmentName>2-Day</CommitmentName>

下午 <CommitmentTime>6:00</CommitmentTime>

<CommitmentSequence>B0218</CommitmentSequence>

<Location>

<ScheduledDeliveryDate>2021-05-28</ScheduledDeliveryDate>

下午 <CutOff>5:30</CutOff>

<Facility>邮局</Facility>

<Street>55 GRASSO PLZ</Street>

<City>SAINT LOUIS</City>

<State>MO</State>

<Zip>63123</Zip>

</Location>

</Commitment>

</ExpressMailCommitmentResponse>

 

Powered by Translations.com GlobalLink OneLink SoftwarePowered By OneLink