USPS Returns Label API

 

USPS Web Tools™

Application 编程接口

User Guide

Version 1.8 (8/2/2023)

 

 

 

 


 

Table of Contents

1.0        Web工具简介. 3

1.1        Before you get started: 3

2.0        USPS Returns Label API 3

2.1        Overview. 3

2.1.1        API Signature. 6

2.2        Request Descriptions. 6

2.2.1        Sample Request 17

2.3        Response Descriptions. 20

2.3.1        Sample Response. 25

3.0        Appendix A -镜像参数选项. 26

4.0        Appendix B – Label Samples. 27

4.1        USPS 返回标签样本-优先邮件返回 Service. 27

4.2        USPS 退货标签样品-优先邮件特快专递退货十大网堵平台. 28

4.3        USPS 退货标签样品-地面优势退货十大网堵平台. 29

5.0        Appendix C – Unique ZIP+4. 30

 


 

1.0        Web工具简介

本文档包含USPS申报表的参考指南 Label API. See the Developer’s Guide 学习访问Web的管理流程 工具api以及调用api和处理的基本机制 the results. 开发人员指南还包含有关测试和 troubleshooting.

Note请求参数部分表示XML 的输入标记,用于生成实时请求,以及对的限制 values allowed. 如果值不正确,将返回错误消息 entered. 另外,要注意某些标记允许的最大字符数量 - an error will 如果传递的值超过这些值则返回 limits. 如果解析表达式或字符限制没有为标记记录 定义为字符串,Web Tools将简单地将字符传递到 允许的最大金额,忽略其余的. 这很重要,因为 结果值可能会阻止正确的响应. 我们建议集成商检查 在API请求中传递的所有值的字符长度,以避免任何错误 截断或不成功的响应.

在构建XML请求时,要特别注意 the order and case for tags. 如果不正确,将返回错误消息 value is entered. 请记住本文档中的所有数据和属性值 是为了说明的目的,并被您的实际值所取代.

 

1.1         在开始之前:

有关登记及领取的资料 开始使用Web工具,请参考 Step-By-Step guide 在Web工具上找到的 Technical Documentation Page.

Note: The Web Tools user ID (i.e.“123ABCD456”)将不适用 yriz.mygreenkeeper.com (also reference: http://reg.mygreenkeeper.com); USPS Web Tools API user ID credentials are 单独的,需要API使用.

额外的新员工培训 在集成商开始使用Web Tools之前是必需的 USPSReturnsLabel API生成USPS申报表 service labels. 集成商应十大网堵平台USPS邮寄 & Shipping Solutions 电话:1-877-672-0007寻求帮助. MSSC的营业时间为 周一至周五7:00 AM-7:00 PM Central. 美国邮政退货网页也可以 be referenced: http://yriz.mygreenkeeper.com/business/return-services.htm

 

2.0        USPS返回标签API

2.1       Overview

Web工具USPS退货 标签API使客户能够接收USPS退货十大网堵平台标签 通过包裹平台使用新的自动退货流程处理. USPS Returns 十大网堵平台帐户持有人须缴付邮费及 通过企业支付系统(EPS)的帐户收取费用,使项目可以 由他们的客户退回(不向他们的客户收费)使用商家 提供USPS退货十大网堵平台标签. API允许集成商请求 USPS Returns 可以邮寄的物品的十大网堵平台标签 使用一等包返回 Service, Priority Mail 退货十大网堵平台和地面退货十大网堵平台. 额外的USPS退货十大网堵平台 details, reference: http://www.federalregister.gov /文件/ 2020/02/25/2020 - 03170 / usps-returns-service.

 

Initial 入职将包括:

第一部分:技术集成专家 (TIS)

·        套餐平台注册

·        USPS Returns enrollment

·        注册易办事帐户 电子资金转移支付USPS退货十大网堵平台邮资. 

·        USPS Web Tools API注册 生成Web Tools用户ID和访问权限 configuration

·        邮件ID (MID)登记

·        客户登记号码(CRID) enrollment

·        目的配置 收货地址(如适用)

Customer Types:

The USPS Returns 标签API将支持以下配置选项 初始客户入职:

·        非显性(SSF)选项: 支持创建返回标签到a 每个Web Tools配置的单个交付目的地地址 UserID. 支持唯一的返回ZIP4. Note: The 能够生成多个交付目的地的退货标签 separate Web Tools UserIDs 对于每个目的地 address.

·        显化(SSF)选项(非 eFulFillment): 支持将返回标签创建到已配置的交付目的地地址 有保险额外十大网堵平台的选项. 支持唯一的返回ZIP4. A 运输十大网堵平台文件将由Web工具提交退货标签 代表积分器.

·        Manifesting (SSF) eFulfillement for Returns Option: 支持创建返回标签 eFulfillment 将客户返回到API中收集的交付目的地地址 请求附加保险十大网堵平台选项. 船舶十大网堵平台文件 将由Web Tools代表集成商提交退货标签. Note: The USPSReturnsLabel API将ams验证 提供的目的地址 eFulFillment 客户或错误将返回. 唯一的zip4不适用于这些 customers.

 

USPS 返回标签API特性

Non-manifesting Option

Manifesting Option (not eFulfillment)

Manifesting Option (eFulfillment)

USPS Returns Services:

-

-

-

·        优先邮件退回十大网堵平台

Available

Available

Available

·        特快专递十大网堵平台

Available

Available

Available

·        地面优势返回十大网堵平台

Available

Available

Available

Extra Services:

-

-

-

·        Insurance

N/A

Available

Available

·        危险品附加十大网堵平台

Available

Available

Available

Ability to use 每个Web Tools有多个交付目的地地址 UserID. (地址收集在XML请求中并提交 fSSF)

N/A

N/A

Available

Ability to 在标签上注明客户参考编号

Available

Available

Available

Ability to specify 标签上注明送货目的地地址

Available

Available

Available

Support Puerto 来自非洲的地址

Available

Available

Available

Support Priority 邮件立方退货定价

TBD

TBD

TBD

Label Sizes/types:

-

-

-

Default (6x4 标签和收据印在同一张纸上.5x11页)枚举:“6X4 page”

Available

Available

Available

·        ZPL(203和300 dpi)

枚举:“4X6ZPL203DPI”和 “4X6ZPL300DPI”

Available

Available

Available

·        True 4x6 portrait

Enumeration: “4X6”

Available

Available

Available

·        True 6x4 landscape

Enumeration: “6X4”

Available

Available

Available

·        真4x4(受限)

TBD

TBD

TBD

USPS Tracking Email

Available

Available

Available

USPS Tracking 电子邮件与PDF返回标签附件

Available

Available

Available

Support unique Returns ZIP4

Available

Available

N/A

Generate 航运十大网堵平台档案

N/A

Available

Available

Label volume reporting

Available

Available

Available

2D IMpb Barcode

Available

Available

Available

Optional Fees and Attributes (i.e., dim wt.) Breakdown

Available

Available

Available


 

2.1.1       API Signature

Scheme

Host

Path

API

XML

http://

secure.shippingapis.com

/ShippingAPI.dll?

API=USPSReturnsLabel

&XML=(see below)

http://

secure.shippingapis.com

/ShippingAPI.dll?

API=USPSReturnsLabelCertify

&XML=(see below)

 

Note: The “USPSReturnsLabelCertify“API是用于测试目的的,不会 生成可用的标签和条形码.

2.2             请求描述

Tag Name

Occurs

Description

Type

Validation

USPSReturnsLabelRequest

Required

Used with API=USPSReturnsLabel

(Alias)

 

USPSReturnsLabelRequest / USERID

Required

此属性指定您的Web Tools user ID. See the Developer's Guide 获取有关获取USERID的信息.

例如:USERID="XXXXXXX"

NMTOKEN

 

USPSReturnsLabelRequest / PASSWORD

Required

此属性指定您的Web Tools password. See the Developer's Guide 查阅有关密码的资料.

For Example: PASSWORD="XXXXXXX"

NMTOKEN

 

USPSReturnsLabelRequest / Option

Optional

For future use.  

String

 

USPSReturnsLabelRequest / Revision

Optional

用于指示API版本. Use a value 返回一个缩短的 IMpb barcode in the <TrackingNumber> tag.

For example: 2

String

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

USPSReturnsLabelRequest / ImageParameters

Required

包含所有请求参数的组 与标签图像生成有关.

(Group)

 

USPSReturnsLabelRequest / ImageParameters / ImageType

Required

Label Image Type. See Appendix A 图像参数选项.

For example: <ImageType>PDFImageType>

String

Enumeration=

· PDF

· TIF

· NONE

· ZPL

USPSReturnsLabelRequest / ImageParameters/ ImageParameter

Optional

返回备用标签图像. See Appendix A 图像参数选项.

 

For example: <ImageParameter>4X6ImageParameter>

String

Default=6X4PAGE

Enumerations=

· 4X6

· 6X4

· 6X4PAGE

· 4X6ZPL203DPI

· 4X6ZPL300DPI

· SEPARATERECEIPTPAGE < /span>

USPSReturnsLabelRequest / CustomerFirstName

有条件要求(仅当 CustomerFirm not provided)

顾客退回包裹的名字. Printed 标签和收据上.

Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. 最少1个字符 required.

 

Note: <CustomerFirstName> and <CustomerLastName> values have a combined 在标签上打印时,限制为32个字符. 超过32的组合值 由于标签上的空间限制,字符将被截断. API 请求有资格接受最多50个字符.

String

minLength=1
maxLength=50

USPSReturnsLabelRequest / CustomerLastName

有条件要求(仅当 CustomerFirm not provided)

客户退回包裹的姓氏. Printed 标签和收据上.

Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. 最少1个字符 required.

 

Note: <CustomerFirstName> and <CustomerLastName> values have a combined 在标签上打印时,限制为32个字符. 超过32的组合值 由于标签上的空间限制,字符将被截断. API request 有资格接受最多50个字符.

String

minLength=1
maxLength=50

USPSReturnsLabelRequest / CustomerFirm

有条件要求(仅当客户第一/最后。 Name not provided)

客户退回包裹的公司名称. Printed 标签和收据上. Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. 最少1个字符 required.

 

Note: <CustomerFirm> 在标签上打印时有32个字符的限制. 值超过32 由于标签上的空间限制,字符将被截断. API 请求有资格接受最多50个字符.

String

minLength=1
maxLength=50

USPSReturnsLabelRequest / CustomerAddress1

有条件要求(如果地址需要) secondary info)

辅助地址单元指示器和 号码(如公寓或套房号码). 例如:“APT 202”或“STE” 100” etc.  

 

Note: 这个标签甚至必须包含在请求中 如果值为空,则返回一个成功的响应. 对于这样的地址 不需要辅助信息,集成商应该包括 “” in the request.

String

minLength=0
maxLength=50

USPSReturnsLabelRequest / CustomerAddress2

Required

退回包裹的客户地址. (主要街道地址). For example: 123 Main St.

String

minLength=1
maxLength=50

USPSReturnsLabelRequest / CustomerUrbanization

有条件的要求 (如果地址在波多黎各)

Urbanization of 顾客退回包裹.

String

minLength=0
maxLength=50

USPSReturnsLabelRequest / CustomerCity

Required

退回包裹的客户所在城市.  

String

minLength=1
maxLength=28

USPSReturnsLabelRequest / CustomerState

Required

客户退回包裹的状态. 值应以两个字母的状态缩写形式传递. For example: <CustomerState>DCCustomerState>  

String

pattern=\w{2}
pattern=  

minLength=2
maxLength=2

USPSReturnsLabelRequest / CustomerZip5

Required

客户退货的邮政编码 package.  

String

pattern=\d{5}  

USPSReturnsLabelRequest / CustomerZip4

Optional

客户返回的ZIP+4代码 package.  

String

pattern=\d{4}
pattern=  

USPSReturnsLabelRequest / POZipCode

有条件要求(如果邮件输入ZIP) 代码不同于CustomerZip5)

ZIP Code of 邮寄邮件的邮局或收集箱. 可能与CustomerZip5不同. 当提供时,此标记将优先于CustomerZip5. Will be used 来填充SSFv2.0 H1 pos. 7入口设施邮政编码字段.

For example: <POZipCode>20770POZipCode>

String

pattern=\d{5}  

USPSReturnsLabelRequest / AllowNonCleansedOriginAddr

Optional

允许未经验证的起源街 Address. 输入“true”以绕过街道地址验证失败/错误或 如果只允许验证过的地址,则为false.

 

Note: 建议始终使用集成商 “假”,以确保没有交付问题. 如果USPS无法验证 街道地址,此标签将“绕过”地址验证错误时为“true” 是否允许创建可能影响交货的标签. The <AllowNonCleansedOriginAddr> excludes City, State, and 邮政编码,必须是有效的成功响应. Reference http://pe.mygreenkeeper.com/text/pub28/28c2_001.htm.

Boolean

Default=false

Enumerations=

· true

· false

USPSReturnsLabelRequest / RetailerATTN

Optional (May be specified when <ReturnsPostageType>=5)

Attention line 零售商地址.

 

If supplied, 这个可选值将覆盖存储在Retailers中的值 WebTools Profile.

 

Note: <RetailerATTN> 在标签上打印时有32个字符的限制. 值超过32 由于标签上的空间限制,字符将被截断. API 请求有资格接受最多50个字符.

String

minLength=0
maxLength=50

USPSReturnsLabelRequest / RetailerFirm

有条件的要求 (When <ReturnsPostageType>=5)

零售商公司名称 退回包裹地址. 印在标签和收据上.

 

<RetailerFirm> is required for Efulfillment customers using <ReturnsPostageType>=5. 最少1个字符.

 

Note: <CustomerFirm> 在标签上打印时有32个字符的限制. 值超过32 由于标签上的空间限制,字符将被截断. API 请求有资格接受最多50个字符.

String

minLength=0
maxLength=50

USPSReturnsLabelRequest / RetailerAddress1

Optional (May be specified when <ReturnsPostageType>=5)

Secondary 地址单元标识符和编号(如公寓或套房号码). 例如:“APT 202”或“STE 100”等.  

 

Note:  may be specified by Efulfillment customers using <ReturnsPostageType>=5. 所提供的值将 重写存储在Retailers中的值 WebTools Profile.  Efulfillment 提供空标记或不提供此标记的客户也将重写 存储在Retailers中的值 WebTools Profile 导致没有显示RetailerAddress1行.

String

minLength=0
maxLength=50

USPSReturnsLabelRequest / RetailerAddress2

有条件的要求 (When <ReturnsPostageType>=5)

零售商地址 包裹在哪里被退回. (主要街道地址). For example: 123 Main St.

 

Note: is required for Efulfillment customers using <ReturnsPostageType>=5. 最少1个字符.

String

minLength=1
maxLength=50

USPSReturnsLabelRequest / RetailerCity

有条件的要求 (When <ReturnsPostageType>=5)

City of Retailer 包裹在哪里被退回.

 

Note: <RetailerCity> is required for Efulfillment customers using <ReturnsPostageType>=5.

String

minLength=1
maxLength=28

USPSReturnsLabelRequest / RetailerState

有条件的要求 (When <ReturnsPostageType>=5)

State of Retailer 包裹在哪里被退回. Value应该以两个字母的形式传递 state abbreviation. For example: <RetailerState >DCRetailerState >  

 

Note: <RetailerState> is required for Efulfillment customers using <ReturnsPostageType>=5.

String

pattern=\w{2}
pattern=  

minLength=2
maxLength=2

USPSReturnsLabelRequest / RetailerZip5

有条件的要求 (When <ReturnsPostageType>=5)

零售商的邮政编码 包裹在哪里被退回.

 

Note: is required for Efulfillment customers using <ReturnsPostageType>=5.

String

pattern=\d{5}  

USPSReturnsLabelRequest / RetailerZip4

有条件的要求 (When <ReturnsPostageType>=5)

邮编+4零售商代码 包裹在哪里被退回.

 

Note: is required for Efulfillment customers using <ReturnsPostageType>=5.

String

pattern=\d{4}
pattern=  

USPSReturnsLabelRequest / RetailerEmail

有条件的要求 (When <ReturnsPostageType>=5)

Email for 退货包的零售商.

 

Note: Either <RetailerEmail> OR <RetailerPhone> is required for Efulfillment customers using <ReturnsPostageType>=5.

String

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

USPSReturnsLabelRequest / RetailerPhone

有条件的要求 (When <ReturnsPostageType>=5)

Phone number for 退货包的零售商.

 

Note: Either <RetailerEmail> OR <RetailerPhone> is required for Efulfillment customers using <ReturnsPostageType>=5.

String

pattern= \s*|[0-9]{10})?

USPSReturnsLabelRequest / WeightInOunces

Optional

用于计算邮资的包裹重量. 物品的重量不得超过70磅(1120盎司).

For example: <WeightInOunces>80WeightInOunces>

 

Note: 如未提供重量,则使用4盎司.

Integer

Default=4

minInclusive=0
maxInclusive=1120  

USPSReturnsLabelRequest / ServiceType

Required

输入一个有效的邮件十大网堵平台 entries:

“PRIORITY” for Priority Mail Return Service.

“EXPRESS” for Priority Mail

特快退货十大网堵平台.

“GROUND” for Ground 优惠退货十大网堵平台.

String

Enumeration=

· PRIORITY

· EXPRESS

· GROUND

USPSReturnsLabelRequest / ReturnsPostageType

有条件的要求 (Required for Efulfillment users)

The Postage Type 查阅退货标签.

 

Note: Required for USPSReturns 登记为 Efulfillment users. Non-Efulfillment 用户可以省略这个标签,也可以使用 empty value.

String

Enumeration=

· 5

USPSReturnsLabelRequest / Width

Optional

值必须是数字. Units are inches.
For example: 5.5

 

Note: If partial 提供维度时,将返回错误响应. 长度,宽度,高度 are 需要准确定价的矩形 任何尺寸超过12英寸的包裹. In addition, Girth 除“长度、宽度、 任何包装尺寸超过12英寸时的高度. For rectangular 包装时,“周长”尺寸必须留空,因为该尺寸仅适用于包装 用于非矩形包装. 尺寸重量的详细信息 价格请参考《网投十大娱乐平台》第123节.1.4 for Retail 邮件及第223条.1.商业邮件6元. http://pe.mygreenkeeper.com/text/dmm300/index.htm   

Decimal

minExclusive=0.0
totalDigits=10

USPSReturnsLabelRequest / Length

Optional

值必须是数字. Units are inches. 与宽度和高度值相比,长度应该是最长的维度 supplied.

For example: 11

 

Note: If partial 提供维度时,将返回错误响应. 长度,宽度,高度 are 需要准确定价的矩形 任何尺寸超过12英寸的包裹. In addition, Girth 除“长度、宽度、 任何包装尺寸超过12英寸时的高度. For rectangular 包装时,“周长”尺寸必须留空,因为该尺寸仅适用于包装 用于非矩形包装. 尺寸重量的详细信息 价格请参考《网投十大娱乐平台》第123节.1.4 for Retail 邮件及第223条.1.商业邮件6元. http://pe.mygreenkeeper.com/text/dmm300/index.htm   

Decimal

minExclusive=0.0
totalDigits=10

USPSReturnsLabelRequest / Height

Optional

值必须是数字. Units are inches.
For example: 7

 

Note: If partial 提供维度时,将返回错误响应. 长度,宽度,高度 are 需要准确定价的矩形 任何尺寸超过12英寸的包裹. In addition, Girth 除“长度、宽度、 任何包装尺寸超过12英寸时的高度. For rectangular 包装时,“周长”尺寸必须留空,因为该尺寸仅适用于包装 用于非矩形包装. 尺寸重量的详细信息 价格请参考《网投十大娱乐平台》第123节.1.4 for Retail 邮件及第223条.1.商业邮件6元. http://pe.mygreenkeeper.com/text/dmm300/index.htm   

Decimal

minExclusive=0.0
totalDigits=10

USPSReturnsLabelRequest / Girth

有条件要求(如果包是 non-rectangular)

Note: 周长只对a有要求 非矩形包. 对于矩形包装,周长必须留空.

 

值必须是数字. Units are inches. Girth is 包装最厚部分周围的距离 (垂直于长度). 有关尺寸重量定价的详情,请 请参阅《网投十大娱乐平台》第123条.1.零售邮件及电子邮件收费4元 Section 223.1.商业邮件6元 http://pe.mygreenkeeper.com/text/dmm300/index.htm.

For example: 25

Note: If 如果提供了部分维度,将返回一个错误响应. (i.e. 长度、宽度和高度都必须提供 Girth).

Decimal

minExclusive=0.0
totalDigits=10

USPSReturnsLabelRequest / Machinable

Optional

可加工的包裹被定义为包裹 小于或等于15“x18”x22“英寸,小于或等于25磅. 任何超过阈值(尺寸或重量)的包裹都将被退回 考虑nonmachinable.

 

注意:API将验证所提供的 尺寸和/或重量决定可加工性. In this case the tag will be ignored. 如果没有提供这些,则 tag will be used to designate if shipment is Machinable (true) 或不可加工(false).

For example: true

Boolean

Default=true

Enumerations=

· true

· false

USPSReturnsLabelRequest / VendorCode

Optional

 

String

minLength=0
maxLength=4

USPSReturnsLabelRequest / VendorProductVersionNumber

Optional

 

String

minLength=0
maxLength=8

USPSReturnsLabelRequest / MailOwnerMID

Optional

 

String

minLength =0

maxLength =9

pattern =\d{9}

pattern =\d{6}

pattern =\d{0}

USPSReturnsLabelRequest / CustomerRefNo

Optional

Used to collect RMA number.

The <CustomerRefNo> value will be used to populate the SSFv2.0 D1 pos. 21客户参考编号字段.

String

minLength=0
maxLength=30

USPSReturnsLabelRequest / PrintCustomerRefNo

Optional

Used to print <CustomerRefNo> value on the label. The <PrintCustomerRefNo> must be set to “true” in order to display <CustomerRefNo> on the label.

Boolean

Default=false

Enumerations=

· true

· false

 

USPSReturnsLabelRequest / CustomerRefNo2

有条件的要求 (When <ReturnsPostageType>=5)

Used to collect merchant ID.

 

Note: is required for Efulfillment customers using <ReturnsPostageType>=5.

String

minLength=0
maxLength=30

USPSReturnsLabelRequest / PrintCustomerRefNo2

Optional

Used to print data on the label. The must be set to “true” in order to display value on the label.

 

Boolean

Default=false

Enumerations=

· true

· false

 

USPSReturnsLabelRequest / SenderName

Optional

用于USPS跟踪邮件. 发送USPS跟踪邮件的个人或公司的名称 notification.

 

Note:生成邮件时不返回 Sample (i.e., API=USPSReturnsLabelCertify) request.  

String

minLength=0
maxLength=50

USPSReturnsLabelRequest / SenderEmail

Optional

Used for the USPS Tracking email. USPS使用的发件人邮箱地址 跟踪电子邮件通知. 必须使用有效的电子邮件地址.

 

Note: <RecipientEmail> 必须填充以生成USPS跟踪电子邮件通知. If <SenderEmail> provided without <RecipientEmail>, 将不会生成USPS跟踪电子邮件通知.

Note:当生成一个样本(1)时,不返回电子邮件.e., API=USPSReturnsLabelCertify) request.  

String

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

USPSReturnsLabelRequest / RecipientName

Optional

Used for the USPS Tracking email. 指示接收的个人或公司的名称 USPS跟踪电子邮件通知. 如果未提供收件人姓名,请发送电子邮件 will be addressed to <RecipientEmail> value provided.

 

Note:当生成一个样本(1)时,不返回电子邮件.e., API=USPSReturnsLabelCertify) request.  

String

minLength=0
maxLength=50

USPSReturnsLabelRequest / RecipientEmail

Optional

Required to 生成USPS跟踪电子邮件. 收件人的接收邮箱地址 USPS跟踪电子邮件通知. 必须使用有效的电子邮件地址.

 

Note:当生成一个样本(1)时,不返回电子邮件.e., API=USPSReturnsLabelCertify) request. 

String

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

USPSReturnsLabelRequest / TrackingEmailPDF

Optional

Used to indicate 如果PDF返回标签将被附加(真)或不(假)到USPS Tracking email.

Boolean

Default=false

Enumerations=

· true

· false

USPSReturnsLabelRequest / ExtraServices

Optional

分组额外的十大网堵平台元素

(Group)

 

USPSReturnsLabelRequest / ExtraServices/ ExtraService

Optional, 无限次的重复

Use to specify extra services. 如果没有指定额外十大网堵平台,USPS跟踪将是 默认,基础十大网堵平台. 

Currently 可用的十大网堵平台有:

 

Service Name

Service ID

Insurance

100

Insurance (Express)

101

Insurance (Priority)

125

HAZMAT Services

Service ID

Air 合格的乙醇包装

810

Class 1 -玩具推进剂/安全保险丝包

811

Class 3 -易燃液体包装

812

Class 7 -放射性材料包装

813

Class 8 -腐蚀性材料包装

814

Class 8 – Nonspillable Wet Battery Package

815

Class 锂电池标记-仅接地包装

816

Class 9 -锂电池-退货包

817

Class 锂电池,包装上有标记

818

Class 9 – Dry Ice Package

819

Class 锂电池,未标记包装

820

Class 9 -磁化材料包装

821

Division 4.易燃固体或安全火柴包

822

Division 5.1 -氧化剂包装

823

Division 5.有机过氧化物包

824

Division 6.1 -有毒材料包装

825

Division 6.2 -感染性物质包装

826

Excepted 数量供应包

827

Ground 仅限有害物质

828

ID8000 消费品包装

829

Lighters Package

830

LTD QTY Ground Package

831

Small 数量供应包

832

 

Note: When <ExtraService>=“125” and <InsuredAmount> is less than or equal to $100,则返回的保险价格为0(“$0”).00”),以反映烘烤 insurance. If <InsuredAmount> is greater than 100美元,退回的保险价格将反映自烘焙以来的额外成本 超出保险范围.

 

Note: 如果HAZMAT额外十大网堵平台“813”和“826”在国内综合时显示 customs form returns, a <CustomsContentType> “危险货物”的字样.

String

whiteSpace=collapse

Enumeration=

· 100

· 101

· 125

HAZMAT Services:

· 810

· 811

· 812

· 813

· 814

· 815

· 816

· 817

· 818

· 819

· 820

· 821

· 822

· 823

· 824

· 825

· 826

· 827

· 828

· 829

· 830

· 831

· 832

 

USPSReturnsLabelRequest / InsuredAmount

有条件的要求 (投保时额外收费也是 indicated)

使用此标签输入保险 金额(如适用).

For example: <InsuredAmount>100.00InsuredAmount

 

Note可获得的最高保险金额可能会因情况而异 返回请求的邮件十大网堵平台类型.

Decimal

minInclusive=0.0
maxInclusive=5000.00

USPSReturnsLabelRequest /ReturnFees

Optional

This tag must be set to “true” for to be returned. This tag is used 因此,客户可以看到他们的邮费需要支付哪些费用.

Boolean

Default=false

Enumerations=

· true

· false

USPSReturnsLabelRequest

Required

Used with API=USPSReturnsLabel 

(Alias)

 

 

2.2.1         Sample Request

 

非显式(SSF) XML Request:

<USPSReturnsLabelRequest USERID="XXXXXXXXX" PASSWORD="XXXXXXXXX">

<ImageParameters>

<ImageType>PDFImageType>

ImageParameters>

<CustomerFirstName>Cust First NameCustomerFirstName>

<CustomerLastName>Cust Last NameCustomerLastName>

<CustomerFirm>Customer FirmCustomerFirm>

PO Box 100

<CustomerUrbanization/>

<CustomerCity>WashingtonCustomerCity>

<CustomerState>DCCustomerState>

20260

1122

<POZipCode>20260POZipCode>

<AllowNonCleansedOriginAddr>falseAllowNonCleansedOriginAddr>

<RetailerATTN>ATTN: Retailer Returns DepartmentRetailerATTN>

<RetailerFirm>Retailer FirmRetailerFirm>

<WeightInOunces>80WeightInOunces>

<ServiceType>PRIORITYServiceType>

4

10

7

2

true

<CustomerRefNo>RMA%23: EE66GG87CustomerRefNo>

<PrintCustomerRefNo>truePrintCustomerRefNo>

EF789UJK

true

<SenderName>Sender Name for EmailSenderName>

<SenderEmail>senderemail@email.comSenderEmail>

<RecipientName>Recipient of EmailRecipientName>

<RecipientEmail>recipientemail@email.comRecipientEmail>

<TrackingEmailPDF>trueTrackingEmailPDF>

<ExtraServices>

<ExtraService>ExtraService>

ExtraServices>

USPSReturnsLabelRequest>

 

显示(SSF) XML Request:

<USPSReturnsLabelRequest USERID="XXXXXXXXX" PASSWORD="XXXXXXXXX">

2

<ImageParameters>

<ImageType>PDFImageType>

<ImageParameter>4X6ImageParameter>

<ImageParameter>SEPARATERECEIPTPAGEImageParameter>

ImageParameters>

<CustomerFirstName>Cust First NameCustomerFirstName>

<CustomerLastName>Cust Last NameCustomerLastName>

<CustomerFirm>Customer FirmCustomerFirm>

150 CALLE A

<CustomerUrbanization>URB REPTO VETERANOCustomerUrbanization>

<CustomerCity>San JuanCustomerCity>

<CustomerState>PRCustomerState>

00926

0221

<POZipCode>20260POZipCode>

<AllowNonCleansedOriginAddr>trueAllowNonCleansedOriginAddr>

<RetailerATTN>ATTN: Retailer Returns DepartmentRetailerATTN>

<RetailerFirm>Retailer FirmRetailerFirm>

<WeightInOunces>10WeightInOunces>

<ServiceType>EXPRESSServiceType>

4

10

7

2

true

<CustomerRefNo>RMA%23: EE66GG87CustomerRefNo>

<PrintCustomerRefNo>truePrintCustomerRefNo>

EF789UJK

true

<SenderName>Sender Name for EmailSenderName>

<SenderEmail>senderemail@email.comSenderEmail>

<RecipientName>Recipient of EmailRecipientName>

<RecipientEmail>recipientemail@email.comRecipientEmail>

<TrackingEmailPDF>trueTrackingEmailPDF>

<ExtraServices>

<ExtraService>101ExtraService>

ExtraServices>

<InsuredAmount>100InsuredAmount>

USPSReturnsLabelRequest>

 

Manifesting (SSF) eFulfillement for返回XML请求:

<USPSReturnsLabelRequest USERID="XXXXXXXXX" PASSWORD="XXXXXXXXX">

2

<ImageParameters>

<ImageType>PDFImageType>

<ImageParameter>6X4PAGEImageParameter>

ImageParameters>

<CustomerFirstName>Cust First NameCustomerFirstName>

<CustomerLastName>Cust Last NameCustomerLastName>

<CustomerFirm>Customer FirmCustomerFirm>

232

PO Box 100

<CustomerUrbanization/>

<CustomerCity>WashingtonCustomerCity>

<CustomerState>DCCustomerState>

20260

1236

<POZipCode>20260POZipCode>

<AllowNonCleansedOriginAddr>trueAllowNonCleansedOriginAddr>

<RetailerATTN>ATTN: Retailer Returns DepartmentRetailerATTN>

<RetailerFirm>Retailer FirmRetailerFirm>

Ste 100

2 Massachusetts Ave NE

<RetailerCity>WashingtonRetailerCity>

<RetailerState>DCRetailerState>

20212

1726

<RetailerEmail>Returns@Retailer.comRetailerEmail>

<RetailerPhone>2125551234RetailerPhone>

<WeightInOunces>10WeightInOunces>

<ServiceType>GROUNDServiceType>

<ReturnsPostageType>5ReturnsPostageType>

12

24

16

0

true

<VendorCode>1000VendorCode>

<VendorProductVersionNumber>102VendorProductVersionNumber>

<MailOwnerMID>817463MailOwnerMID>

<CustomerRefNo>RMA%23: EE66GG87CustomerRefNo>

<PrintCustomerRefNo>truePrintCustomerRefNo>

EF789UJK

true

<SenderName>Sender Name for EmailSenderName>

<SenderEmail>senderemail@email.comSenderEmail>

<RecipientName>Recipient of EmailRecipientName>

<RecipientEmail>recipientemail@email.comRecipientEmail>

<TrackingEmailPDF>trueTrackingEmailPDF>

<ExtraServices>

<ExtraService>100ExtraService>

ExtraServices>

<InsuredAmount>100InsuredAmount>

<ReturnFees>trueReturnFees>

USPSReturnsLabelRequest>

 

2.3             Response Descriptions

Tag Name

Occurs

Description

Type

Validation

USPSReturnsLabelResponse

Required

 

(Alias)

 

USPSReturnsLabelResponse / BarcodeNumber

Required

的追踪/确认号码 package. 这个标记返回一个长表单 IMpb that 包括路由信息:

42020904198592019 xxxxxxxxxxxxxxxxx

String

 

USPSReturnsLabelResponse / TrackingNumber

Required

的追踪/确认号码 package. 这个标记返回一个缩短的 IMpb that 以通道应用程序ID开头:

92019 xxxxxxxxxxxxxxxxx

TrackingNumber is available when is greater than or equal to “2”

String

 

USPSReturnsLabelResponse / LabelImage

Optional

Binary 以选定的形式表示标签(PDF, TIF). Default response will contain a single <LabelImage> tag containing label and receipt on the same page.

 

Note: Not returned when <ImageType>=“NONE”在请求中指定.

base64Binary

Default= <LabelImage> contains label and receipt on same page

USPSReturnsLabelResponse / ReceiptImage

Optional

Binary 以所选格式表示收据(PDF, TIF).  

 

Note: 只有在请求中指定了SEPARATERECEIPTPAGE时才返回.

base64Binary

 

USPSReturnsLabelResponse / RetailerATTN

Optional

Attention line 零售商收到退货包裹的时间.

 

String

maxLength=50

USPSReturnsLabelResponse / RetailerFirm

Optional

Firm Name of 收到退货包裹的零售商. 已配置的“交付目的地” Company” used. Future enhancements will also use <RetailerFirm>.

 

Note: <RetailerFirm> 由于空格,在标签上打印时,值在32个字符之后被截断 limitations. 有资格返回最多50个字符的API响应.

String

MaxLength=50

USPSReturnsLabelResponse / RetailerAddress1

Optional

Address of 收到退货包裹的零售商. 辅助地址单元指示器和 号码(如公寓或套房号码). 例如:“APT 202”或“STE” 100” etc. 配置使用“送货目的地址s2”.

String

 

USPSReturnsLabelResponse / RetailerAddress2

Required

Address of 收到退货包裹的零售商. 已配置的“交付目的地” Address” used.

String

 

USPSReturnsLabelResponse / RetailerCity

Required

City 零售商收到退货包裹的时间. 配置使用“交付目的地城市”.

String

 

USPSReturnsLabelResponse /
RetailerState

Required

State of 收到退货包裹的零售商. 已配置的“交付目的地” State” used.

String

 

USPSReturnsLabelResponse / RetailerZip5

Required

Zip5 of Retailer 收到退货包裹. 已设定“派递目的地邮编” used.

String

pattern=\d{5}  

USPSReturnsLabelResponse / RetailerZip4

Required

Zip4 of Retailer 收到退货包裹. 已设定“派递目的地邮编” used.

String

 

USPSReturnsLabelResponse / RDC

Required

Retail 标签上印着配送代码,用于美国邮政处理.

 

Note: The following MCSetCodes 用于返回 确定RDC的API:

Service

MCSetCode

Ground Return Service

006

头等包裹退货 Service

005

优先邮件回寄十大网堵平台

003

String

 

USPSReturnsLabelResponse / Postage

Required

Postage amount 浏览“退货”套餐.

 

Note: 不包括任何额外十大网堵平台费或 surcharges.

String

minLength=0  

USPSReturnsLabelResponse / ExtraServices

Optional

Groups extra 请求中指定的十大网堵平台信息.

(Group)

 

USPSReturnsLabelResponse / ExtraServices / ExtraService

Optional, 无限次的重复

Groups extra 请求中指定的十大网堵平台信息.

(Group)

 

USPSReturnsLabelResponse / ExtraServices / ExtraService / ServiceID

Optional

Extra Service ID included in request

String

 

USPSReturnsLabelResponse / ExtraServices / ExtraService / ServiceName

Optional

Extra Service name

String

 

USPSReturnsLabelResponse / ExtraServices / ExtraService / Price

Optional

Extra Service fee 

Decimal

 

USPSReturnsLabelResponse / Zone

Required

Postal Zone. 美国邮政定义的距离代码分配给每个产地和 目的地邮政编码配对在每个国家的邮政编码号码. These 距离代码,称为区域,被指定为“1到9”."

String

 

USPSReturnsLabelResponse / DimensionalWeight

Optional

Dimensional 用来决定邮资的包裹重量. 邮资按实际重量计算(注明) in <WeightInOunces>) or the dimensional 重量,取较大的.

For example, <DimensionalWeight>14.0DimensionalWeight>

For details on 尺寸重量定价,请参阅《网投十大娱乐平台》一节 123.1.4零售邮件和第223条.1.商业邮件6元. http://pe.mygreenkeeper.com/text/dmm300/index.htm

String

 

USPSReturnsLabelResponse / CarrierRoute

Required

Carrier Route

String

 

USPSReturnsLabelResponse / LogMessage

Optional

Messaging for 这个API的集成商. 它可能包含有关此的其他信息 特定的请求/响应,或网投十大娱乐平台API或Web的一般信息 Tools. 在典型的实现中,每当遇到这个标记时 消息被写入控制台日志文件以供以后分析.  

String

 

USPSReturnsLabelResponse / Fees

Optional

Returned when “Fees” is True

 

Dimensional 重量定价将包括长度和体积费用,以考虑成本 处理超大包裹

 

 

USPSReturnsLabelResponse / Fee

Required

 

String

 

USPSReturnsLabelResponse / Fee / FeeType

Required

Indicates 适用于包裹的费用类型:

- Non Standard Length Fee

- Non Standard Volume Fee

String

 

USPSReturnsLabelResponse / Fee / FeeType / FeePrice

Required

Non Standard Length Fee(s)

a. 15" < x < 22" = $0 (for all packages)

b. 22" < x < 30" = $2 (for DDU entered packages)

c. 22" < x < 30" = $3 (for DNDC/DSCF entered packages)

d. 22" < x < 30" = $4 (for all other packages)

e. x > 30" = $7.50(对于DDU输入的包)

f. x > 30" = $11.25(对于DNDC/DSCF输入的包)

g. x > 30" = $15(所有其他套餐)

 

- Non Standard Volume Fee(s)

a. x > 2 立方英尺(3546立方英寸)= 15美元(所有套餐)

 

Live Animal 运输费用(年代)

a. $0.20 for all packages

String

 

USPSReturnsLabelResponse / Fees / Fee / FeeType / FeePrice / FeeInformation

Required

Fee Information indicates the fee is

String

 

USPSReturnsLabelResponse / Fees / Fee / FeeType / FeePrice / FeeInformation / FeeInfo FeeInfoType=”PriceType

Required

Fee Information indicates the fee is

String

 

USPSReturnsLabelResponse / Attributes

Required

When <ReturnFees> = True,新的Attributes标签将返回显示Oversize费用和/或Dimensional Weight fees.

影响价格的任何未来包属性 返回的将包含在属性标记中.

String

 

USPSReturnsLabelResponse / Attributes / AttributeKey

Required

Attribute Key:

·        DimensionalWeightR = RetailRate

·        DimensionalWeightCB = Commercial Rate

·        DimensionalWeightCP = Commerical Plus Rate

·        Oversized

String

 

USPSReturnsLabelResponse

Required

 

(Alias)

 

 

2.3.1     Sample Response

 

XML Response:

<USPSReturnsLabelCertifyResponse>

    420202121726925989XXXXXXXXXXXXXXXX

    <TrackingNumber>925989XXXXXXXXXXXXXXXXTrackingNumber>

    <LabelImage>--- Base 64 Binary stream Suppressed for documentation---LabelImage>

    <RetailerATTN>ATTN: Retailer Returns DepartmentRetailerATTN>

    <RetailerFirm>RETAILER FIRMRetailerFirm>

    STE 100

    2 MASSACHUSETTS AVE NE

    <RetailerCity>WASHINGTONRetailerCity>

    <RetailerState>DCRetailerState>

    20212

    1726

    0001

    43.71

    <ExtraServices>

        <ExtraService>

            <ServiceID>100ServiceID>

            <ServiceName>InsuranceServiceName>

            3.40

        ExtraService>

    ExtraServices>

    01

    <DimensionalWeight>28DimensionalWeight>

    <CarrierRoute>C000CarrierRoute>

   

       

            <FeeType>Nonstandard Length fee > 22 in.FeeType>

            <FeePrice>4.00FeePrice>

       

       

            <FeeType>Nonstandard Volume fee > 2 cu. ft.FeeType>

            <FeePrice>15.00FeePrice>

       

   

   

        DimensionalWeight">28

   

USPSReturnsLabelCertifyResponse>

 

 


 

3.0        Appendix A – 图像参数选项

 

Image Parameter(s)

Description

Receipt

Image Type

6X4 PAGE

返回1张图片:完整的第8页.5x11 with 6x4标签和收据(当前默认).

是的,包含在单个图像中

PDF, TIF

6X4 PAGE

SEPARATERECEIPTPAGE

2 images returned:

1) Full Page 8.5x11 with 6x4 label

2)完整第8页的收据.5x11

是的,但是在单独的整版上

PDF, TIF

4X6

返回1个图像:True 4x6

No

PDF, TIF

4X6

SEPARATERECEIPTPAGE

2 images returned:

1) True 4x6 label

2)完整第8页的收据.5x11

是的,但是在单独的整版上

 

6X4

返回1个图像:True 6x4

No

PDF, TIF

6X4

SEPARATERECEIPTPAGE

2 images returned:

1) True 6x4 label True

2)完整第8页的收据.5x11

Yes

PDF, TIF

4X6ZPL203DPI

返回1张图像:4x6 ZPL 203

No

ZPL

4X6ZPL300DPI

返回1张图像:4x6 ZPL 300

No

ZPL

 

4.0        附录B -标签样品

4.1         美国邮政总局返回标签样品-优先邮件返回 Service

Letter

描述以中等置信度自动生成

Figure 1: USPS优先邮件退回十大网堵平台标签

4.2         美国邮政总局返回标签样品-优先邮件快递 Return Service

Figure 2:特快专递十大网堵平台标签

4.3         USPS返回标签样品-地面优势返回 Service

Diagram, schematic

描述自动生成

Figure 3: USPS地面优势退货十大网堵平台标签

5.0        附录C -唯一的ZIP+4

Web Tools USPSReturnsLabel allows 唯一返回ZIP4,可以用来代替从AMS返回的ZIP4 in the XML response , barcode, label, receipt, and SSF.

上下文:今天,本地AMS生成一个 unique returns 批量较大的目的地ZIP4会退回发货人,但不会 在AMS DB外部与其他内部系统共享此数据. As a result, 唯一的返回ZIP4将无法通过AMS验证并标准化为ZIP4 physical address. 对于Web Tools USPS Returns API,一个配置的唯一ZIP4 允许客户绕过AMS ZIP4.

Ex. 目的地地址:“16840 BUCCANEER LN休斯顿,得克萨斯州 77058 + XX50* -唯一的ZIP4是“XX50”,AMS标准化为“2563”-当 如果在Web Tools中配置了唯一的ZIP4选项,则唯一返回ZIP4 "XX50" is used.