Merchandise Return V4.0 Label API

 

USPS Web Tools™

Application Programming Interface

用户指南

Version 3.4 (05/21/2020)

 

 

 

 

 

 


 


目录

1.0        Introduction to Web Tools. 3

1.1        Before you get started: 3

2.0        Merchandise Return V4.0 Label API 3

2.1        Overview. 3

2.1.1        API Signature. 3

2.2        Request Descriptions. 3

2.2.1        Sample Request 7

2.3        Response Descriptions. 8

2.3.1        Sample Response. 9

3.0        Appendix A. 11

3.1        Merchandise Return V4 Label Sample. 11

 


 

1.0        Introduction to Web Tools

This document contains a Reference Guide to the Merchandise Return Bulk Label API. 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.

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.

注意:The Web Tools user ID you receive upon registration will not work at: https://returns.usps.com. For issues with that page, please contact returns@usps.com. The USPS Returns web page can also be referenced: 

https://zh.usps.com/business/return-services.htm.  

 

2.0        Merchandise Return V4.0 Label API

2.1       Overview

The Merchandise Return V4.0 Label API enables customers to receive Merchandise Return labels. The Merchandise Return Service allows authorized permit holders to pay postage and extra service fees so that items can be returned by their customers (at no charge to their customers) using merchant provided pre-paid labels. The API allows integrators to request Merchandise Return labels for items that can be mailed using First-Class Package Service, Priority Mail, and Parcel Select Ground.

 

注意: The “MerchReturnCertifyV4” API is for testing purposes and will not generate usable labels and barcodes.

2.1.1         API Signature

Scheme

Host

小道

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=MerchandiseReturnV4

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=MerchReturnCertifyV4

&XML=(see below)

2.2             Request Descriptions

Tag Name

Occurs

描述

类型

Validation

EMRSV4.0Request

需要

Used with API=MerchandiseReturnV4  

(Alias)

 

EMRSV4.0Request / USERID

需要

This attribute specifies your WebTools ID. See the Developers Guide for information on obtaining your USERID

例如:

<USERID = ”XXXXXXXXXX”>

NMTOKEN

 

EMRSV4.0Request / Option

需要

Specifies what type of #10 window envelopes will be used to mail the label to the Customer address.  

String

default=LEFTWINDOW

Enumeration=

·        RIGHTWINDOW

·        LEFTWINDOW  

EMRSV4.0Request / Revision

Optional repeating up to 1 times

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. 例如:1 

String

minLength=0
pattern=\d{1}
pattern=  

EMRSV4.0Request / CustomerName

需要

Name of customer returning package.  

String

minLength=1
maxLength=100 

EMRSV4.0Request / CustomerAddress1

需要

Secondary address unit designator and number (such as an apartment or suite number (APT 202, STE 100)).  

String

minLength=1
maxLength=50

EMRSV4.0Request / CustomerAddress2

需要

Address of customer returning the package.  

String

minLength=1
maxLength=50  

EMRSV4.0Request / CustomerCity

需要

City of customer returning the package.  

String

minLength=1
maxLength=28

EMRSV4.0Request / CustomerState

需要

State of customer returning the package.  

String

pattern=\w{2}
pattern=  

minLength=2
maxLength=2

EMRSV4.0Request / CustomerZip5

需要

ZIP Code of customer returning the package.  

String

pattern=\d{5}  

EMRSV4.0Request / CustomerZip4

需要

ZIP+4 Code of customer returning the package.  

String

pattern=\d{4}
pattern=  

EMRSV4.0Request / RetailerName

需要

Name of Retailer receiving the return package.  

String

minLength=1
maxLength=50

EMRSV4.0Request / RetailerAddress

需要

Address of Retailer receiving the return package.  

String

minLength=1
maxLength=50 

EMRSV4.0Request / PermitNumber

需要

Permit number provided to Retailer by the local post office.  

String

pattern=\d+  

EMRSV4.0Request / PermitIssuingPOCity

需要

Post Office City that issued the permit.  

String

minLength=1
maxLength=28

EMRSV4.0Request / PermitIssuingPOState

需要

Post Office State that issued the permit.  

String

pattern=\w{2}
pattern=  

minLength=2
maxLength=2

EMRSV4.0Request / PermitIssuingPOZip5

需要

ZIP Code of Post Office that issued the permit.  

String

pattern=\d{5}  

EMRSV4.0Request / PDUFirmName

Optional

Postage Delivery Unit Name

String

minLength=0
maxLength=50  

EMRSV4.0Request / PDUPOBox

需要

Postage Delivery Unit Post Office Box or Street Address.  

String

minLength=1
maxLength=24  

EMRSV4.0Request / PDUCity

需要

Postage Delivery Unit City. Supply either City and State or PO Box with ZIP Code.  

String

minLength=0
maxLength=28

EMRSV4.0Request / PDUState

需要

Postage Delivery Unit State. Supply either City and State or PO Box with ZIP Code.  

String

pattern=\w{2}
pattern=  

minLength=2
maxLength=2

EMRSV4.0Request / PDUZip5

需要

Postage Delivery Unit ZIP Code. Supply either City and State or PO Box with ZIP Code.  

String

pattern=\d{5}
pattern=  

EMRSV4.0Request / PDUZip4

需要

Postage Delivery Unit ZIP+4 Code.  

String

pattern=\d{4}
pattern=  

EMRSV4.0Request / ServiceType

需要

Enter one of the valid entries: “Priority” (for Priority Mail), “First Class Package Service”, or “Ground”.

String

Enumeration=

·        Priority

·        First Class Package Service

·        Ground

EMRSV4.0Request / DeliveryConfirmation

需要

Enter "true" for Delivery Confirmation.  

Boolean

 

EMRSV4.0Request / InsuranceValue

需要

Numeric currency with dollars and cents (no dollar sign). If insurance is not Required, leave value blank. A value of “0.00” will result in an error being returned.  

Decimal
String

minExclusive=0.0
maxLength=0  

EMRSV4.0Request / MailingAckPackageID

Optional

Deprecated. Retailer assignable number. Superseded by the Merchandise Return Service Number assigned automatically.  

String

minLength=0
maxLength=24  

EMRSV4.0Request / WeightInPounds

需要

Estimated weight is allowed. First Class Mail cannot exceed 13 ounces.  

Integer

minInclusive=0
maxInclusive=70  

EMRSV4.0Request / WeightInOunces

需要

Value must be numeric.  

Integer

minInclusive=0
maxInclusive=1120  

EMRSV4.0Request / RMA

需要

RMA restricted to 2-7 decimal digits when RMAPICFlag=True.  

String

minLength=0
maxLength=24  

EMRSV4.0Request / RMAPICFlag

需要

RMAPIC indicator. RMA will display in the barcode if ‘True’.

String

Enumeration=

·        True

·        False

EMRSV4.0Request / ImageType

需要

One of the valid entries: “TIF”, “PDF”  

String

Enumeration

·        PDF

·        TIF

EMRSV4.0Request / SenderName

Optional

The name of the person or company sending the email. 注意:no email is returned when generating a Sample label request.  

String

 

EMRSV4.0Request / SenderEMail

Optional

E-mail address of sender. Valid e-mail addresses must be used. 注意:No e-mail is returned when generating a Sample label request.  

String

pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}
pattern=  

EMRSV4.0Request / RecipientName

Optional

The name of the person or company receiving the email. 注意:no email is returned when generating a Sample label request.  

String

 

EMRSV4.0Request / RecipientEMail

Optional

E-mail address of recipient. Valid e-mail addresses must be used. 注意:No e-mail is returned when generating a Sample label request.  

String

pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}
pattern=  

EMRSV4.0Request / RMABarcode

Optional

Value of 'true' generates the RMA barcode on the label. System will assume "false" if no value is entered.  

Boolean

default=false

Enumerations=

·        true

·        false

EMRSV4.0Request / AllowNonCleansedDestAddr

Optional

Value of 'true' bypasses destination address cleansing.  Non-cleansed destination addresses may result in undeliverable packages.

Boolean

default=false

Enumerations=

·        true

·        false

EMRSV4.0Request / AllowNonCleansedCustAddr

Optional

Value of 'true' bypasses customer address cleansing.  Non-cleansed customer addresses may result in undeliverable packages.

Boolean

default=false

Enumerations=

·        true

·        false

EMRSV4.0Request / NineDigitRoutingZip

Optional

 

String

Enumerations=

·        true

·        false

EMRSV4.0Request / Content

Optional

Special Contents of package

(group)

 

EMRSV4.0Request / Content / ContentType

Required – if content included

Use to specify ContentType.  Available types are:

ContentType

危险物品

易腐邮件

易碎品

示例:< ContentType >HAZMAT</ ContentType >

注意:  USPS-produced packaging, including Flat Rate and Regional Rate, cannot be used to ship live animals.  Error response will be returned.

String

Enumeration=

·        HAZMAT 

·        PERISHABLE

·        FRAGILE

EMRSV4.0Request / GroundOnly

Optional

Specifies the package is to be transported Ground Only

Boolean

default=false

EMRSV4.0Request / Oversized

Optional

Specifies the package is Oversized

Boolean

default=false

EMRSV4.0Request

需要

Used with API=MerchandiseReturnV4  

(Alias)

 

2.2.1         Sample Request

<EMRSV4.0Request USERID="XXXXXXXXXXXX" >

<Option>RIGHTWINDOW</Option>

<CustomerName>Janice Dickens</CustomerName>

<CustomerAddress1>Ste 201</CustomerAddress1>

<CustomerAddress2>7 N Wilkes Barre Blvd</CustomerAddress2>

<CustomerCity>Wilkes Barre</CustomerCity>

<CustomerState>PA</CustomerState>

<CustomerZip5>18702</CustomerZip5>

<CustomerZip4 />

<RetailerName>XYZ Corp.</RetailerName>

<RetailerAddress>123 Main St</RetailerAddress>

<PermitNumber>293829</PermitNumber>

<PermitIssuingPOCity>New York</PermitIssuingPOCity>

<PermitIssuingPOState>NY</PermitIssuingPOState>

<PermitIssuingPOZip5>10001</PermitIssuingPOZip5>

<PDUFirmName>PDU Firm Co.</PDUFirmName>

<PDUPOBox>PO Box 100</PDUPOBox>

<PDUCity>Wilkes Barre</PDUCity>

<PDUState>PA</PDUState>

<PDUZip5>18702</PDUZip5>

<PDUZip4>1234</PDUZip4>

<ServiceType>Priority</ServiceType>

<DeliveryConfirmation>False</DeliveryConfirmation>

<InsuranceValue />

<MailingAckPackageID>ID00001</MailingAckPackageID>

<WeightInPounds>0</WeightInPounds>

<WeightInOunces>10</WeightInOunces>

<RMA>RMA 123456</RMA>

<RMAPICFlag>False</RMAPICFlag>

<ImageType>TIF</ImageType>

<RMABarcode>False</RMABarcode>

</EMRSV4.0Request>

2.3             Response Descriptions

Tag Name

Occurs

描述

类型

Validation

EMRSV4.0Response

需要

 

(Alias)

 

EMRSV4.0Response / Zone

需要

Postal Zone Indicates the number of postal rate zones between the origin and destination ZIP Codes.  

String

 

EMRSV4.0Response / MerchandiseReturnLabel

需要

Binary representation of the label in the form selected (PDF, TIF).  

base64Binary

 

EMRSV4.0Response / (choice)

需要

One of two mutually-exclusive package numbers will be returned depending on the value of the EMRSV4.0Request/DeliveryConfirmation boolean.

(choice)

 

EMRSV4.0Response / (choice) / DeliveryConfirmationNumber

Optional

Delivery Confirmation number for the package.  

String

 

EMRSV4.0Response / (choice) / MerchandiseReturnNumber

Optional

Merchandise Return Service Number for the package.  

String

 

EMRSV4.0Response / InsuranceCost

需要

Cost of the insurance.  

Decimal

 

EMRSV4.0Response / PDUFirmName

Optional

Postage Delivery Unit Name. Returned if provided in request XML.

String

 

EMRSV4.0Response / PDUPOBox

需要

Postage Delivery Unit Post Office Box or Street Address.  

String

 

EMRSV4.0Response / PDUPOBoxAbbreviation

Optional

Abbreviated Postage Delivery Unit Post Office Box or Street Address

String

 

EMRSV4.0Response / PDUCity

需要

Postage Delivery Unit City. Supply either City and State or PO Box with ZIP Code.  

String

 

EMRSV4.0Response / PDUCityAbbreviation

Optional

Abbreviated Postage Delivery Unit City. Supply either City and State or PO Box with ZIP Code.  

String

 

EMRSV4.0Response / PDUState

需要

Postage Delivery Unit State.  

String

 

EMRSV4.0Response / PDUZip5

需要

Postage Delivery ZIP Code.  

String

pattern=\d{5}  

EMRSV4.0Response / PDUZip4

需要

 

String

 

EMRSV4.0Response / Postnet

需要

Postage Delivery Unit text representation of Postnet barcode. Deprecated; the Postnet barcode is no longer displayed on the label.  

String

minLength=0  

EMRSV4.0Response / CustomerAddress1

需要

Secondary address unit designator and number (such as an apartment or suite number (APT 202, STE 100)).  

String

minLength=0  

EMRSV4.0Response / CustomerAddress2

需要

Address of customer returning the package.  

String

minLength=1  

EMRSV4.0Response / CustomerCity

需要

City of customer returning the package.  

String

minLength=1  

EMRSV4.0Response / CustomerState

需要

State of customer returning the package.  

String

length=2  

EMRSV4.0Response / CustomerZip5

需要

ZIP Code of customer returning the package.  

String

pattern=\d{5}  

EMRSV4.0Response / CustomerZip4

需要

ZIP+4 Code of customer returning the package. May be blank.  

String

pattern=\d{4}
pattern=  

EMRSV4.0Response / CustomerPostnet

需要

Customer text representation of Postnet barcode. Deprecated; the Postnet barcode is no longer displayed on the label.  

String

minLength=0  

EMRSV4.0Response / RDC

Optional repeating up to 1 time

Retail Distribution Code printed on label for USPS processing purposes.

String

 

EMRSV4.0Response / LogMessage

Optional repeating up to 1 time

A text message for integrators of this API. It may contain additional information about this particular request/response, or general information about the API or Web Tools. In typical implementations, whenever this tag is encountered, the message is written to the console log file for later analysis.  

String

 

EMRSV4.0Response

需要

 

(Alias)

 

2.3.1         Sample Response

<EMRSV4.0Response>

<Zone>1</Zone>

<MerchandiseReturnLabel>

--!Suppressed--!

</MerchandiseReturnLabel>

<MerchandiseReturnNumber>420187039211700000000000044284</MerchandiseReturnNumber>

<InsuranceCost>0</InsuranceCost>

<PDUFirmName>PDU FIRM CO.</PDUFirmName>

<PDUPOBox>PO BOX 100</PDUPOBox>

<PDUCity>WILKES BARRE</PDUCity>

<PDUState>PA</PDUState>

<PDUZip5>18703</PDUZip5>

<PDUZip4/>

<Postnet>18703</Postnet>

<CustomerAddress1>STE 201</CustomerAddress1>

<CustomerAddress2>7 N WILKES BARRE BLVD</CustomerAddress2>

<CustomerCity>WILKES BARRE</CustomerCity>

<CustomerState>PA</CustomerState>

<CustomerZip5>18702</CustomerZip5>

<CustomerZip4>5241</CustomerZip4>

<CustomerPostNet>18702524151</CustomerPostNet>

</EMRSV4.0Response>

 


 

3.0        Appendix A

3.1         Merchandise Return V4 Label Sample

 

Powered By OneLink