Package Pickup API

 

 

USPS Web Tools™

Application Programming Interface

用户指南

Version 2.6 (8/1/2023)

 

 

 

 

 

 

 

 

 


目录

1.0         Introduction to Web Tools. 3

1.2         Before you get started: 3

2.0         Package Pickup Web Tools APIs. 3

2.1         Overview. 3

3.0         Package Pickup Availability API 4

3.1         Overview. 4

3.1.1      API Signature. 4

3.2         Request Descriptions. 5

3.2.1      Sample Request 6

3.3         Response Descriptions. 6

3.3.1      Sample Response. 7

4.0         Package Pickup Schedule API 7

4.1         Overview. 7

4.1.1      API Signature. 7

4.2         Request Descriptions. 7

4.2.1      Sample Request 12

4.3         Response Descriptions. 12

4.3.1      Sample Response. 14

5.0         Package Pickup Cancel API 14

5.1         Overview. 14

5.1.1      API Signature. 14

5.2         Request Descriptions. 14

5.2.1      Sample Request 16

5.3         Response Descriptions. 16

5.3.1      Sample Response. 17

6.0         Package Pickup Change API 17

6.1         Overview. 17

6.1.1      API Signature. 17

6.2         Request Descriptions. 17

6.2.1      Sample Request 21

6.3         Response Descriptions. 21

6.3.1      Sample Response. 23

7.0         Package Pickup Inquiry API 23

7.1         Overview. 23

7.1.1      API Signature. 24

7.2         Request Descriptions. 24

7.2.1      Sample Request 25

7.3         Response Descriptions. 25

7.3.1      Sample Response. 27

 


1.0   Introduction to Web Tools

This document contains a Reference Guide to the Web Tools Package Pickup 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.2     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   Package Pickup Web Tools APIs

2.1     Overview

The Package Pickup Web Tools APIs provide convenience to you and your customers. Your carrier will pick up your packages on the next USPS delivery day (Monday through Saturday, excluding holidays) for free. Package Pickup is available for sending packages using Priority Mail Express, Priority Mail, Gound Advantage, international delivery services, or for returned merchandise. Customers requiring pickup of their packages by the USPS currently have two pickup options available to them: next delivery day Package Pickup and Pickup On-Demand. This Web Tools API User Guide applies to next delivery day Package Pickup only. Pickup On-Demand is only available through the USPS website. The information below is presented to illustrate the differences between these two options:

包裹领取

Pickup on Demand(按需取件)

Free, regardless of the number of packages.

Per pickup fee, regardless of the number of packages.

Your carrier picks up the next USPS delivery day when your mail is delivered.

Packages are picked up in a specified timeframe.

Available with domestic Priority Mail Express, Priority Mail, ExpressMail, Ground Advantage Commercial, international delivery services, or for merchandise returns.

Available for Express Mail, Priority Mail, single piece paid Standard Post, Global Express Guaranteed®, Express Mail International, Priority Mail International.

Requests must be received by 2:00 AM CT. You can edit or cancel a scheduled pickup request until 2:00 AM CT on the day of the pickup.

Allow a two-hour timeframe for pickups. Pickup must be cancelled before 上午 5:00 local time the day of the pickup.

Individual items cannot exceed 70 pounds.

Individual items cannot exceed 70 pounds.

Postage must be prepaid and attached to package(s).

Apply postage to each package.

Packages must be properly sealed and ready for shipment.

Have your packages ready for pickup at the time and day specified.

Packages requiring insurance services need to be taken to a post office.

 

 

Full Package Pickup functionality relies on the implementation of five separate APIs:

·        Package Pickup Availability API

·        Package Pickup Schedule API

·        Package Pickup Cancel API

·        Package Pickup Change API

·        Package Pickup Inquiry API

The five Package Pickup Web Tools work together to provide seamless service to you and your customers. Specifically, the functions of each are as follows:

  1. Package Pickup Availability API checks the availability for Package Pickup at a specific address and informs the user of the first available date for pickup. 包裹领取并非适用于所有地址。
  2. Package Pickup Schedule API schedules a Package Pickup and provides the user a confirmation number for the scheduled pickup. Prior to making a Pickup Schedule call, it is recommended to use the Pickup Availability API to confirm that service is available.
  3. Package Pickup Cancel API cancels a scheduled Package Pickup. To use either the Pickup Cancel or Pickup Change API, the exact data returned from the original Pickup Schedule API response must be entered. You must enter address information and the confirmation number. The confirmation number alone cannot be used to cancel or change a scheduled pickup. Address information must be identical to what was entered when the pickup was scheduled. To verify the accuracy of your data, you can use the Pickup Inquiry API.
  4. Package Pickup Change API allows users to change certain data in their original Pickup Schedule request. To use either the Pickup Cancel or Pickup Change API, the exact data from the original Pickup Schedule API request must be entered. You must enter address information and the confirmation number. The confirmation number alone cannot be used to cancel or change a scheduled pickup. The name and phone number of the sender can be changed, along with the number and types of package services, the weight of the packages, and the location of the pickup. Address data and the confirmation number cannot be changed and must be identical to the original Schedule request. To verify the accuracy of your data, you can use the Pickup Inquiry API. Refer to the Delivery Timeline section for information regarding deadlines for changing pickups.
  5. Package Pickup Inquiry API provides the data contained in your original Pickup Schedule request. To use either the Pickup Cancel or Pickup Change API, the exact data from the original Schedule API response must be entered. By using the Pickup Inquiry API, you can obtain the data needed.

For more information regarding Package Pickup Services, please visit https://faq.usps.com/s/article/What-is-Package-Pickup.

 

3.0   Package Pickup Availability API

3.1     Overview

The Package Pickup Availability API checks the availability for Package Pickup at a specific address and informs the user of the first available date for pickup. Package Pickup is not available for all addresses.

3.1.1   API Signature

Scheme

Host

小道

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=CarrierPickupAvailability

&XML=(see below)

 

 

3.2     Request Descriptions

Tag Name

Occurs

描述

类型

Validation

CarrierPickupAvailabilityRequest

需要

 

(Alias)

 

CarrierPickupAvailabilityRequest / USERID

需要

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

例如:USERID="XXXXXXX"

NMTOKEN

 

CarrierPickupAvailabilityRequest / PASSWORD

Optional

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

例如:PASSWORD="XXXXXXX"

NMTOKEN

 

CarrierPickupAvailabilityRequest/ FirmName

Optional

Use this tag for a firm or company name. FirmName is Optional except if needed to uniquely identify an address. Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address.

示例:<FirmName>ABC Company</FirmName>

String

minLength=0
maxLength=50

CarrierPickupAvailabilityRequest/ SuiteOrApt

需要

Use this tag for an apartment or suite number. SuiteOrApt is Optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building.

例如:<SuiteOrApt>Suite 777</SuiteOrApt>

String

minLength=0
maxLength=50

CarrierPickupAvailabilityRequest/ Address2

需要

Use this tag for a street address.

例如:<Address2>1390 Market Street</Address2>

String

minLength=0
maxLength=50

CarrierPickupAvailabilityRequest/ Urbanization

需要

Use this tag for Urbanization (for Puerto Rico only). ZIP Code prefixes 006 to 009, if area is so designated.

String

minLength=0
maxLength=28

CarrierPickupAvailabilityRequest/ City

需要

Use this tag for a city. Either ZIP5 or City and State are Required.

例如: <City>Houston</City>

String

minLength=0
maxLength=30

CarrierPickupAvailabilityRequest/ State

需要

Use this tag for a state abbreviation. Either ZIP5 or City and State are Required.

例如: <State>TX</State>

String

minLength=0
maxLength=2

CarrierPickupAvailabilityRequest/ ZIP5

需要

Use this tag for a 5 digit ZIP Code. Either ZIP5 or City and State are Required.

例如: <ZIP5>77058</ZIP5>

String

minLength=0
maxLength=5

CarrierPickupAvailabilityRequest/ ZIP4

需要

Maximum characters allowed: 4.

例如: <ZIP4>1234</ZIP4>

String

minLength=0
maxLength=4

CarrierPickupAvailabilityRequest/ Date

Optional

Use this tag to request a pickup date/time.

例如: 2006-05-04T18:13:51.0Z

String

minOccurs=0
maxOccurs=1

CarrierPickupAvailabilityRequest

需要

 

(Alias)

 

3.2.1   Sample Request

<CarrierPickupAvailabilityRequest USERID="XXXXXXXXX" PASSWORD="">

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

</CarrierPickupAvailabilityRequest>

3.3     Response Descriptions

Tag Name

Occurs

描述

类型

Validation

CarrierPickupAvailabilityResponse

需要

 

(Alias)

 

CarrierPickupAvailabilityResponse/ FirmName

Optional

Firm name sending request

String

 

CarrierPickupAvailabilityResponse/ SuiteOrApt

需要

Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address)

String

 

CarrierPickupAvailabilityResponse/ Address2

需要

Pickup address

String

 

CarrierPickupAvailabilityResponse/ Urbanization

需要

城市化

String

 

CarrierPickupAvailabilityResponse/ City

需要

Pickup city

String

 

CarrierPickupAvailabilityResponse/ State

需要

Pickup state

String

 

CarrierPickupAvailabilityResponse/ ZIP5

需要

Pickup ZIP Code

String

 

CarrierPickupAvailabilityResponse/ ZIP4

需要

Pickup ZIP Code+4

String

 

CarrierPickupAvailabilityResponse/ DayOfWeek

需要

Day of week for pickup

String

 

CarrierPickupAvailabilityResponse/ Date

需要

Scheduled date for pickup

String

 

CarrierPickupAvailabilityResponse/ CarrierRoute

Optional

Carrier Route (can be C for City, H for Highway, R for Rural)

String

 

CarrierPickupAvailabilityResponse

需要

 

(Alias)

 

3.3.1   Sample Response

<CarrierPickupAvailabilityResponse>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<DayOfWeek>Monday</DayOfWeek>

<Date>4/01/2004</Date>

<CarrierRoute>C</CarrierRoute>

</CarrierPickupAvailabilityResponse>

4.0   Package Pickup Schedule API

4.1     Overview

The Package Pickup Schedule API schedules a Package Pickup and provides the user a confirmation number for the scheduled pickup. Prior to making a Pickup Schedule call, it is recommended to use the Pickup Availability API to confirm that service is available.

4.1.1   API Signature

Scheme

Host

小道

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=CarrierPickupSchedule

&XML=(see below)

4.2     Request Descriptions

Tag Name

Occurs

描述

类型

Validation

CarrierPickupScheduleRequest

需要

 

(Alias)

 

CarrierPickupScheduleRequest / USERID

需要

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

例如:USERID="XXXXXXX"

NMTOKEN

 

CarrierPickupScheduleRequest / PASSWORD

Optional

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

例如:PASSWORD="XXXXXXX"

NMTOKEN

 

CarrierPickupScheduleRequest / FirstName

需要

Only alpha characters, apostrophes, spaces, periods, and hyphens "-" may be used.

For example: <FirstName>John</FirstName>

String

minLength=0
maxLength=50

CarrierPickupScheduleRequest / LastName

需要

Only alpha characters, apostrophes, spaces, periods and hyphens "-" may be used.

例如:<LastName>Doe</LastName>

String

minLength=0
maxLength=50

CarrierPickupScheduleRequest / FirmName

Optional

Only alpha and numeric characters, apostrophes, spaces, hyphens "-" and ampersands "&" may be used.

Use this tag for a firm or company name. 

Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address.

注意:FirmName is Optional except if the First Name and Last Name tags are null.

例如: <FirmName>ABC Company</FirmName>

String

minLength=0
maxLength=50

CarrierPickupScheduleRequest / SuiteOrApt

需要

Apartment or suite number. Optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building.

例如:<SuiteOrApt>Suite 777</SuiteOrApt>

String

minLength=0
maxLength=50

CarrierPickupScheduleRequest / Address2

需要

Street address.

例如:<Address2>1390 MARKET STREET</Address2>

String

minLength=0
maxLength=50

CarrierPickupScheduleRequest / Urbanization

需要

Use this tag for Urbanization (for Puerto Rico only). ZIP Code prefixes 006 to 009, if area is so designated.

String

minLength=0
maxLength=28

CarrierPickupScheduleRequest / City

需要

City name. Either ZIP5 or City and State are required.

For example: <City>Houston</City>

String

minLength=0
maxLength=30

CarrierPickupScheduleRequest / State

需要

State abbreviation. Either ZIP5 or City and State are required.

例如: <State>TX</State>

String

minLength=0
maxLength=2

CarrierPickupScheduleRequest / ZIP5

需要

5-digit ZIP Code. Either ZIP5 or City and State are required.

For example: <ZIP5>77058</ZIP5>

String

minLength=0
maxLength=5

CarrierPickupScheduleRequest / ZIP4

需要

Use this tag for a 4 digit ZIP Code.

例如: <ZIP4>1234</ZIP4>

String

minLength=0
maxLength=4

CarrierPickupScheduleRequest / Phone

需要

Two formats are allowed: (###) 123-4567 or ###-123-4567. 

例如:

 <Phone>5555551234</Phone>

or <Phone>555-555-1234</Phone>

String

minLength=0
maxLength=14

CarrierPickupScheduleRequest / Extension

Optional

Optional value for Phone Extension. 

例如: <Extension>201</Extension>

String

minOccurs=0

minLength=0
maxLength=4

CarrierPickupScheduleRequest / Package

需要

No values entered with this tag. <ServiceType> and <Count> tags are embedded under this. Refer to the XML request example section, below, to see how these embedded tags are formatted. If the <Count> for a service type is zero, you do not need to encode a <Package> but you must have at least one <Package> with embedded <ServiceType> and <Count> tags.

(Group)

 

CarrierPickupScheduleRequest / Package/ ServiceType

需要

This tag is embedded under the <Package> tag.

If your pickup contains more than one Service Type, use additional <Package> tags for each service type with the accompanying <ServiceType> and <Count> tags. Refer to the XML Request Example below to see how these embedded tags are formatted.

For example: <ServiceType>PriorityMailExpress</ServiceType>

 

:A pickup cannot be scheduled or changed when there are only packages with <ServiceType>="OtherPackages

String

minLength="0"

Enumeration=

· PriorityMailExpress

· PriorityMail

· ExpressMail

· GroundAdvantage

· Returns

· International

· OtherPackages

CarrierPickupScheduleRequest / Package/ Count

需要

This tag is embedded under the <Package> tag.  Enter the number of packages for the accompanying <ServiceType> tag.  Maximum characters allowed: 3 or 999 packages. If your pickup contains more than one Service Type, use additional <Package> tags for each service type with the accompanying <ServiceType> and <Count> tags. Refer to the XML request example section, below, to see how these embedded tags are formatted.

例如:<Count>2</Count>

String

minLength=0
maxLength=3

minInclusive=1
maxInclusive=999

CarrierPickupScheduleRequest / EstimatedWeight

需要

Enter the estimated aggregate weight (in pounds) of all packages being picked up. 

For example: <EstimatedWeight>14</EstimatedWeight>

String

minLength=0
maxLength=5

CarrierPickupScheduleRequest / PackageLocation

需要

Enter one of the following values:

注意:"Other" requires information in the value for the <SpecialInstructions> tag.

例如:<PackageLocation>Front Door</PackageLocation>

String

Enumeration=

· Front Door

· Back Door

· Side Door

· Knock on Door/Ring Bell

· Mail Room

· Office

· Reception

· In/At Mailbox

· Other

CarrierPickupScheduleRequest / SpecialInstructions

Optional / Required

Value Required when PackageLocation is “Other”.

Only alpha, numeric, commas, periods, apostrophes, _, &, -, ( ), ?, #, / +, @ and space characters may be used.

例如:<SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>

String

minLength=0
maxLength=255

CarrierPickupScheduleRequest / EmailAddress

Optional

If provided, email notifications will be sent confirming package pickup, or request changes and cancellations. Maximum characters allowed: 50.

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

String

minOccurs=0

minLength=0
maxLength=255

CarrierPickupScheduleRequest

需要

 

(Alias)

 

4.2.1   Sample Request

<CarrierPickupScheduleRequest USERID="XXXXXXXXX" PASSWORD="">

<FirstName>John</FirstName>

<LastName>Doe</LastName>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>5555551234</Phone>

<Extension>201</Extension>

<Package>

<ServiceType>PriorityMailExpress</ServiceType>

<Count>2</Count>

</Package>

<Package>

<ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>

</CarrierPickupScheduleRequest>

4.3     Response Descriptions

Tag Name

Occurs

描述

类型

Validation

CarrierPickupScheduleResponse

需要

 

(Alias)

 

CarrierPickupScheduleResponse / FirstName

需要

First name of person sending request.

String

 

CarrierPickupScheduleResponse / LastName

需要

Last name of person sending request.

String

 

CarrierPickupScheduleResponse / FirmName

Optional

Firm name sending request (if supplied in request).

String

 

CarrierPickupScheduleResponse / SuiteOrApt

需要

Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address).

String

 

CarrierPickupScheduleResponse / Address2

需要

Pickup address

String

 

CarrierPickupScheduleResponse / Urbanization

需要

Urbanization (if supplied in request).

String

 

CarrierPickupScheduleResponse / City

需要

Pickup city.

String

 

CarrierPickupScheduleResponse / State

需要

Pickup state.

String

 

CarrierPickupScheduleResponse / ZIP5

需要

Pickup ZIP Code.

String

 

CarrierPickupScheduleResponse / ZIP4

需要

Pickup ZIP Code+4.

String

 

CarrierPickupScheduleResponse / Phone

需要

Phone number of the sender.

String

 

CarrierPickupScheduleResponse / Extension

需要

Phone extension of sender (if supplied in request).

String

 

CarrierPickupScheduleResponse / Package

需要

Packages to be picked up.  Can be multiple <Packages> with accompanying <ServiceType> and <Count> tags.

(Group)

 

CarrierPickupScheduleResponse / Package/ ServiceType

需要

Types of package services requested.

String

 

CarrierPickupScheduleResponse / Package/ Count

需要

Number of packages for each service type requested.

String

 

CarrierPickupScheduleResponse / EstimatedWeight

需要

Total estimated weight of all packages to be picked up.

String

 

CarrierPickupScheduleResponse / PackageLocation

需要

Location of pickup.

String

 

CarrierPickupScheduleResponse / SpecialInstructions

需要

Special instructions for pickup.

String

 

CarrierPickupScheduleResponse / ConfirmationNumber

需要

Confirmation number for pickup.

String

 

CarrierPickupScheduleResponse / DayOfWeek

需要

Day of week for pickup.

String

 

CarrierPickupScheduleResponse / Date

需要

Scheduled date for pickup.

String

 

CarrierPickupScheduleResponse / CarrierRoute

Optional

Carrier Route (can be C for City, H for Highway, R for Rural).

String

 

CarrierPickupScheduleResponse / EmailAddress

Optional

Email Address (if supplied in request).

String

 

CarrierPickupScheduleResponse

需要

 

(Alias)

 

4.3.1   Sample Response

<CarrierPickupScheduleResponse>

<FirstName>John</FirstName>

<LastName>Doe</LastName>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension>201</Extension>

<Package>

<ServiceType>PriorityMailExpress</ServiceType>

<Count>2</Count>

</Package>

<Package>

<ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions> Packages are behind the screen door.</SpecialInstructions>

<ConfirmationNumber>ABC12345</ConfirmationNumber>

<DayOfWeek>Monday</DayOfWeek>

<Date>04/01/2004</Date>

<CarrierRoute>C</CarrierRoute>

</CarrierPickupScheduleResponse>

 

5.0   Package Pickup Cancel API

5.1     Overview

The Package Pickup Cancel API cancels a scheduled Package Pickup. To use either the Pickup Cancel or Pickup Change Web Tools, the exact data from the original Schedule API response must be entered. You must enter address information and the confirmation number. Confirmation number alone cannot be used to cancel or change a scheduled pickup. Address information must be identical to what was entered when the pickup was scheduled.

5.1.1   API Signature

Scheme

Host

小道

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=CarrierPickupCancel

&XML=(see below)

5.2     Request Descriptions

Tag Name

Occurs

描述

类型

Validation

CarrierPickupCancelRequest

需要

 

(Alias)

 

CarrierPickupCancelRequest / USERID

需要

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

例如:USERID="XXXXXXX"

NMTOKEN

 

CarrierPickupCancelRequest / PASSWORD

Optional

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

例如:PASSWORD="XXXXXXX"

NMTOKEN

 

CarrierPickupCancelRequest/ FirmName

Optional

Maximum characters allowed: 50. Only alpha and numeric characters, apostrophes, spaces, hyphens "-" and ampersands "&" may be used.

Firm or company name is optional except if needed to uniquely identify an address. Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address.

例如: <FirmName>ABC Company</FirmName>

String

minLength=0
maxLength=50

CarrierPickupCancelRequest/ SuiteOrApt

需要

Apartment or suite number. Optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building.

例如: <SuiteOrApt>Suite 777</SuiteOrApt>

String

minLength=0
maxLength=50

CarrierPickupCancelRequest/ Address2

需要

Street address.

例如: <Address2>1390 MARKET STREET</Address2>

String

minLength=0
maxLength=50

CarrierPickupCancelRequest/ Urbanization

需要

Urbanization (for Puerto Rico only). ZIP Code prefixes 006 to 009, if area is so designated.

String

minLength=0
maxLength=28

CarrierPickupCancelRequest/ City

需要

City name. Either ZIP5 or City and State are Required

例如: <City>Houston</City>

String

minLength=0
maxLength=30

CarrierPickupCancelRequest/ State

需要

State abbreviation. Either ZIP5 or City and State are Required.

例如: <State>TX</State>

String

minLength=0
maxLength=2

CarrierPickupCancelRequest/ ZIP5

需要

5 digit ZIP Code. Either ZIP5 or City and State are Required.

例如: <ZIP5>77058</ZIP5>

String

minLength=0

maxLength=5

CarrierPickupCancelRequest/ ZIP4

需要

4 digit ZIP Code. 

 例如: <ZIP4>1234</ZIP4>

String

minLength=0

maxLength=4

CarrierPickupCancelRequest/ ConfirmationNumber

需要

Enter exact Confirmation Number returned with Package Pickup Schedule request.

例如: <ConfirmationNumber>ABC12345</ConfirmationNumber>

String

minLength=0

maxLength=30

CarrierPickupCancelRequest

需要

 

(Alias)

 

5.2.1   Sample Request

<CarrierPickupCancelRequest USERID="XXXXXXXXX" PASSWORD="">

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<ConfirmationNumber>ABC12345</ConfirmationNumber>

</CarrierPickupCancelRequest>

5.3     Response Descriptions

Tag Name

Occurs

描述

类型

Validation

CarrierPickupCancelResponse

需要

 

(Alias)

 

CarrierPickupCancelResponse/ FirmName

需要

Firm name sending request (if supplied in request)

String

 

CarrierPickupCancelResponse/ SuiteOrApt

需要

Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address)

String

 

CarrierPickupCancelResponse/ Address2

需要

Pickup address

String

 

CarrierPickupCancelResponse/ Urbanization

需要

Urbanization (if supplied in request)

String

 

CarrierPickupCancelResponse/ City

需要

Pickup city

String

 

CarrierPickupCancelResponse/ State

需要

Pickup state

String

 

CarrierPickupCancelResponse/ ZIP5

需要

Pickup ZIP Code

String

 

CarrierPickupCancelResponse/ ZIP4

需要

Pickup ZIP Code+4 (if supplied in request)

String

 

CarrierPickupCancelResponse/ ConfirmationNumber

需要

Confirmation number for pickup

String

 

CarrierPickupCancelResponse/ Status

需要

Status of request to cancel

String

 

CarrierPickupCancelResponse

需要

Type of Response

(Alias)

 

5.3.1   Sample Response

<CarrierPickupCancelResponse>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<ConfirmationNumber>ABC12345</ConfirmationNumber>

<Status>Your pickup request was cancelled.</Status>

</CarrierPickupCancelRequest>

 

6.0   Package Pickup Change API

6.1     Overview

Allows users to change certain data in their original Pickup Schedule API request. To use either the Pickup Cancel or Pickup Change API, the exact data from the original Pickup Schedule API response must be entered. You must enter address information and the confirmation number. The confirmation number alone cannot be used to cancel or change a scheduled pickup. The number and types of package services, the weight of the packages, and the location of the pickup can be changed. Address data and the confirmation number cannot be changed and must be identical to the original Schedule request. To verify the accuracy of your data, you can use the Pickup Inquiry API. 

6.1.1   API Signature

Scheme

Host

小道

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=CarrierPickupChange

&XML=(see below)

6.2     Request Descriptions

Tag Name

Occurs

描述

类型

Validation

CarrierPickupChangeRequest

需要

 

(Alias)

 

CarrierPickupChangeRequest / USERID

需要

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

例如:USERID="XXXXXXX"

NMTOKEN

 

CarrierPickupChangeRequest / PASSWORD

Optional

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

例如:PASSWORD="XXXXXXX"

NMTOKEN

 

CarrierPickupChangeRequest/ FirstName

需要

Only alpha characters, apostrophes, spaces, periods and hyphens "-" may be used.

例如: <FirstName>John</FirstName>

String

minLength=0
maxLength=50

CarrierPickupChangeRequest/ LastName

需要

Only alpha characters, apostrophes, spaces, periods and hyphens "-" may be used.

例如: <LastName>Doe</LastName>

String

minLength=0
maxLength=50

CarrierPickupChangeRequest/ FirmName

Optional

Only alpha and numeric characters, apostrophes, spaces, hyphens "-" and ampersands "&" may be used.

Use this tag for a firm or company name.  FirmName is Optional except if First Name and Last Name tags are null.  Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address.

例如: <FirmName>ABC Company</FirmName>

String

minLength=0
maxLength=50

CarrierPickupChangeRequest/ SuiteOrApt

Optional

Apartment or suite number. Optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building.

例如: <SuiteOrApt>Suite 777</SuiteOrApt>

String

minLength=0
maxLength=50

CarrierPickupChangeRequest/ Address2

需要

Use this tag for a street address.

例如:<Address2>1390 MARKET STREET</Address2>

String

minLength=0
maxLength=50

CarrierPickupChangeRequest/ Urbanization

需要

Use this tag for Urbanization (for Puerto Rico only).  ZIP Code prefixes 006 to 009, if area is so designated.

String

minLength=0
maxLength=28

CarrierPickupChangeRequest/ City

需要

Use this tag for a city.  Either ZIP5 or City and State are Required.

例如: <City>Houston</City>

String

minLength=0
maxLength=30

CarrierPickupChangeRequest/ State

需要

Use this tag for a state abbreviation.  Either ZIP5 or City and State are Required.

例如: <State>TX</State>

String

minLength=0
maxLength=2

CarrierPickupChangeRequest/ ZIP5

需要

Use this tag for a 5 digit ZIP Code. Either ZIP5 or City and State are Required.

例如: <ZIP5>77058</ZIP5>

String

minLength=0
maxLength=5

CarrierPickupChangeRequest/ ZIP4

需要

Use this tag for a 4 digit ZIP Code.

例如: <ZIP4>1234</ZIP4>

String

minLength=0
maxLength=4

CarrierPickupChangeRequest/ Phone

需要

Two formats are allowed: (###) 123-4567 or ###-123-4567. 

例如: <Phone>(555) 555-1234</Phone>

or <Phone>555-555-1234</Phone>

String

minLength=0
maxLength=14

CarrierPickupChangeRequest/ Extension

需要

Extension related to the Phone Number

For example: <Extension>201</Extension>

String

minLength=0
maxLength=4

CarrierPickupChangeRequest/ Package

需要

No values entered with this tag.  <ServiceType> and <Count> tags are embedded under this. 

Refer to the XML request example section, below, to see how these embedded tags are formatted. If the <Count> for a service type is zero, you do not need to encode a <Package> but you must have at least one <Package> with embedded <ServiceType> and <Count> tags.

(Group)

 

CarrierPickupChangeRequest/ Package/ ServiceType

需要

This tag is embedded under the <Package> tag. 

If your pickup contains more than one Service Type, use additional <Package> tags for each service type with the accompanying <ServiceType> and <Count> tags.  Refer to the Live XML Request Example section, below, to see how these embedded tags are formatted.

例如: <ServiceType>PriorityMailExpress</ServiceType>

 

:A pickup cannot be scheduled or changed when there are only packages with <ServiceType>= "OtherPackages

String

Enumerations:

· PriorityMailExpress

· PriorityMail

· ExpressMail

· GroundAdvantage

· Returns

· International

· OtherPackages

CarrierPickupChangeRequest/ Package/ Count

需要

This tag is embedded under the <Package> tag.  Enter the number of packages for the accompanying <ServiceType> tag. Maximum characters allowed: 3 or 999 packages There must be at least one Priority Mail Express Package or one Priority Mail package or one returned merchandise package to make this a valid request.  If your pickup contains more than one Service Type, use additional <Package> tags for each service type with the accompanying <ServiceType> and <Count> tags.  Refer to the Live XML Request Example section, below, to see how these embedded tags are formatted.

例如: <Count>2</Count>

String

minLength=0
maxLength=3

minInclusive=1
maxInclusive=999

CarrierPickupChangeRequest/ EstimatedWeight

需要

Enter the estimated aggregate weight (in pounds) of all packages being picked up. 

For example: <EstimatedWeight>14</EstimatedWeight>

String

minLength=0
maxLength=5

CarrierPickupChangeRequest/ PackageLocation

需要

注意:"Other" requires information in the value for the <SpecialInstructions> tag.

例如: <PackageLocation>Front Door</PackageLocation>

String

Enumeration:

· Front Door

· Back Door

· Side Door

· Knock on Door/Ring Bell

· Mail Room

· Office

· Reception

· In/At Mailbox

· Other

CarrierPickupChangeRequest/ SpecialInstructions

Optional / Required

Only alpha, numeric, commas, periods, apostrophes, _, &, -, ( ), ?, #, / +, @ and space characters may be used.

Required when Package Location tag is “Other”

例如: <SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>

String

minLength=0
maxLength=255

CarrierPickupChangeRequest/ ConfirmationNumber

需要

Enter exact Confirmation Number returned with Package Pickup Schedule request.

例如: ConfirmationNumber>ABC12345</ConfirmationNumber>

String

minLength=0
maxLength=30

CarrierPickupChangeRequest/ EmailAddress

Optional

If provided, email notifications will be sent confirming package pickup, or request changes and cancellations. Maximum characters allowed: 50.

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

String

minOccurs="0"

minLength=0
maxLength=50

CarrierPickupChangeRequest

需要

 

(Alias)

 

6.2.1   Sample Request

<CarrierPickupChangeRequest USERID="XXXXXXXXX" PASSWORD="">

<FirstName>John</FirstName>

<LastName>Doe</LastName>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension>201</Extension>

<Package>

<ServiceType>PriorityMailExpress</ServiceType>

 <Count>2</Count>

</Package>

<Package>

 <ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions> Packages are behind the screen door.</SpecialInstructions>

<ConfirmationNumber>ABC12345</ConfirmationNumber>

</CarrierPickupChangeRequest>

6.3     Response Descriptions

Tag Name

Occurs

描述

类型

Validation

CarrierPickupChangeResponse

需要

 

(Alias)

 

CarrierPickupChangeResponse/ FirstName

需要

First name of person sending request

String

 

CarrierPickupChangeResponse/ LastName

需要

Last name of person sending request

String

 

CarrierPickupChangeResponse/ FirmName

Optional

Firm name sending request (if supplied in request)

String

 

CarrierPickupChangeResponse/ SuiteOrApt

需要

Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address)

String

 

CarrierPickupChangeResponse/ Address2

需要

Pickup address

String

 

CarrierPickupChangeResponse/ Urbanization

需要

Urbanization (if supplied in request)

String

 

CarrierPickupChangeResponse/ City

需要

Pickup city

String

 

CarrierPickupChangeResponse/ State

需要

Pickup state

String

 

CarrierPickupChangeResponse/ ZIP5

需要

Pickup ZIP Code

String

 

CarrierPickupChangeResponse/ ZIP4

需要

Pickup ZIP Code+4

String

 

CarrierPickupChangeResponse/ Phone

需要

Phone number of sender

String

 

CarrierPickupChangeResponse/ Extension

需要

Phone extension of sender (if supplied in request)

String

 

CarrierPickupChangeResponse/ Package

需要

Packages to be picked up (multiple <Package> tags can be returned with accompanying <ServiceType> and <Count> tags.

(group)

 

CarrierPickupChangeResponse/ Package/ ServiceType

需要

Types of package services requested

String

 

CarrierPickupChangeResponse/ Package/ Count

需要

Number of packages for each service type requested

String

 

CarrierPickupChangeResponse/ EstimatedWeight

需要

Total estimated weight of all packages to be picked up

String

 

CarrierPickupChangeResponse/ PackageLocation

需要

Location of pickup

String

 

CarrierPickupChangeResponse/ SpecialInstructions

Optional

Special instructions for pickup

String

 

CarrierPickupChangeResponse/ ConfirmationNumber

需要

Confirmation number for pickup

String

 

CarrierPickupChangeResponse/ DayOfWeek

需要

Day of week for pickup

String

 

CarrierPickupChangeResponse/ Date

需要

Scheduled date for pickup

String

 

CarrierPickupChangeResponse/ Status

Optional

Status of request to change

String

 

CarrierPickupChangeResponse/ EmailAddress

Optional

Email Address (if supplied in request)

String

 

CarrierPickupChangeResponse

需要

 

(Alias)

 

6.3.1   Sample Response

<CarrierPickupChangeResponse>

<FirstName>John</FirstName>

<LastName>Doe</LastName>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension>201</Extension>

<Package>

<ServiceType>PriorityMailExpress</ServiceType>

 <Count>2</Count>

</Package>

<Package>

<ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>

<ConfirmationNumber>ABC12345</ConfirmationNumber>

<DayOfWeek>Monday</DayOfWeek>

<Date>04/01/2004</Date>

<Status>成功更新</Status>

</CarrierPickupChangeResponse>

 

7.0   Package Pickup Inquiry API

7.1     Overview

The Package Pickup Inquiry API provides the data contained in your original Pickup Schedule request. To use either the Pickup Cancel or Pickup Change API, the exact data from the original Schedule response must be entered. By using the Pickup Inquiry API, you can obtain the data needed.

 7.1.1  API Signature

Scheme

Host

小道

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=CarrierPickupInquiry

&XML=(see below)

7.2     Request Descriptions

Tag Name

Occurs

描述

类型

Validation

CarrierPickupInquiryRequest

需要

 

(Alias)

 

CarrierPickupInquiryRequest / USERID

需要

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

例如:USERID="XXXXXXX"

NMTOKEN

 

CarrierPickupInquiryRequest / PASSWORD

Optional

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

例如:PASSWORD="XXXXXXX"

NMTOKEN

 

CarrierPickupInquiryRequest / FirmName

Optional

Only alpha and numeric characters, apostrophes, spaces, hyphens "-" and ampersands "&" may be used.

Firm or company name is optional except if needed to uniquely identify an address. Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address.

例如: <FirmName>ABC Company</FirmName>

String

minLength=0
maxLength=50

CarrierPickupInquiryRequest / SuiteOrApt

需要

Apartment or suite number is optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building.

例如: <SuiteOrApt>Suite 777</SuiteOrApt>

String

minLength=0
maxLength=50

CarrierPickupInquiryRequest / Address2

需要

Use this tag for a street address.

例如:<Address2>1390 MARKET STREET</Address2>

String

minLength=0
maxLength=50

CarrierPickupInquiryRequest / Urbanization

需要

Use this tag for an Urbanization (for Puerto Rico only). ZIP Code prefixes 006 to 009, if area is so designated.

String

minLength=0
maxLength=28

CarrierPickupInquiryRequest / City

需要

Use this tag for a city. Either ZIP5 or City and State are Required

例如: <City>Houston</City>

String

minLength=0
maxLength=30

CarrierPickupInquiryRequest / State

需要

Use this tag for a state abbreviation. Either ZIP5 or City and State are Required.

例如: <State>TX</State>

String

minLength=0
maxLength=2

CarrierPickupInquiryRequest / ZIP5

需要

Use this tag for a 5 digit ZIP Code. Maximum characters allowed: 5. Either ZIP5 or City and State are Required.

例如: <ZIP5>77058</ZIP5>

String

minLength=0
maxLength=5

CarrierPickupInquiryRequest / ZIP4

需要

Maximum characters allowed: 4.

例如: <ZIP4>1234</ZIP4>

String

minLength=0
maxLength=4

CarrierPickupInquiryRequest / ConfirmationNumber

需要

Enter exact Confirmation Number returned with Package Pickup Schedule request.

例如: <ConfirmationNumber>ABC12345</ConfirmationNumber>

String

minLength=1
maxLength=30

CarrierPickupInquiryRequest

需要

 

(Alias)

 

7.2.1   Sample Request

<CarrierPickupInquiryRequest USERID="XXXXXXXXX" PASSWORD="">

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 MARKET STREET</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<ConfirmationNumber>ABC12345</ConfirmationNumber>

</CarrierPickupInquiryRequest>

7.3     Response Descriptions

Tag Name

Occurs

描述

类型

Validation

CarrierPickupInquiryResponse/

需要

 

(Alias)

 

CarrierPickupInquiryResponse/ FirstName

需要

First name of person sending request

String

 

CarrierPickupInquiryResponse/ LastName

需要

Last name of person sending request

String

 

CarrierPickupInquiryResponse/ FirmName

需要

Firm name sending request (if supplied in request)

String

 

CarrierPickupInquiryResponse/ SuiteOrApt

需要

Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address)

String

 

CarrierPickupInquiryResponse/ Address2

需要

Pickup address

String

 

CarrierPickupInquiryResponse/ Urbanization

需要

Urbanization (if supplied in request)

String

 

CarrierPickupInquiryResponse/ City

需要

Pickup city

String

 

CarrierPickupInquiryResponse/ State

需要

Pickup state

String

 

CarrierPickupInquiryResponse/ ZIP5

需要

Pickup ZIP Code

String

 

CarrierPickupInquiryResponse/ ZIP4

需要

Pickup ZIP Code+4

String

 

CarrierPickupInquiryResponse/ Phone

需要

Phone number of the sender.

String

 

CarrierPickupInquiryResponse/ Extension

需要

Phone extension of sender (if supplied in request)

String

 

CarrierPickupInquiryResponse/ Package

需要

Packages to be picked up (multiple <Package> tags can be returned with accompanying <ServiceType> and <Count> tags.

(group)

 

CarrierPickupInquiryResponse/ Package/ ServiceType

需要

Types of package services requested

String

 

CarrierPickupInquiryResponse/ Package/ Count

需要

Number of packages for each service type requested

String

 

CarrierPickupInquiryResponse/ EstimatedWeight

需要

Total estimated weight of all packages to be picked up

String

 

CarrierPickupInquiryResponse/ PackageLocation

需要

Location of pickup

String

 

CarrierPickupInquiryResponse/ SpecialInstructions

需要

Special instructions for pickup

String

 

CarrierPickupInquiryResponse/ ConfirmationNumber

需要

Confirmation number for pickup

String

 

CarrierPickupInquiryResponse/ DayOfWeek

需要

Day of week for pickup

String

 

CarrierPickupInquiryResponse/ Date

需要

Scheduled date for pickup

String

 

CarrierPickupInquiryResponse/ EmailAddress

Optional

电子邮件地址

String

 

CarrierPickupInquiryResponse/

需要

 

(Alias)

 

7.3.1   Sample Response

<CarrierPickupInquiryResponse>

<FirstName>John</FirstName>

<LastName>Doe</LastName>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>5555551234</Phone>

<Extension>201</Extension>

<Package>

<ServiceType>PriorityMailExpress</ServiceType>

<Count>2</Count>

</Package>

<Package>

<ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions> Packages are behind the screen door.</SpecialInstructions>

<ConfirmationNumber>ABC12345</ConfirmationNumber>

<DayOfWeek>Monday</DayOfWeek>

<Date>04/01/2004</Date>

</CarrierPickupInquiryResponse>

 

Powered by Translations.com GlobalLink OneLink SoftwarePowered By OneLink