Class: UspsApi::ReturnsPackage

Inherits:
BaseModel
  • Object
show all
Defined in:
lib/usps_api/models/returns_package.rb

Overview

ReturnsPackage Model.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from BaseModel

#check_for_conflict, #process_additional_properties, #process_array, #process_basic_value, #process_hash, #to_hash, #to_json

Constructor Details

#initialize(weight:, length:, height:, width:, mail_class:, processing_category:, weight_uom: WeightUom::LB, dimensions_uom: DimensionsUom::ENUM_IN, girth: SKIP, has_nonstandard_characteristics: false, customer_reference: SKIP, extra_services: SKIP, package_options: SKIP, destination_entry_facility_address: SKIP, induction_zip_code: SKIP, shipper_visibility_method: SKIP, additional_properties: nil) ⇒ ReturnsPackage

Returns a new instance of ReturnsPackage.



252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/usps_api/models/returns_package.rb', line 252

def initialize(weight:, length:, height:, width:, mail_class:,
               processing_category:, weight_uom: WeightUom::LB,
               dimensions_uom: DimensionsUom::ENUM_IN, girth: SKIP,
               has_nonstandard_characteristics: false,
               customer_reference: SKIP, extra_services: SKIP,
               package_options: SKIP,
               destination_entry_facility_address: SKIP,
               induction_zip_code: SKIP, shipper_visibility_method: SKIP,
               additional_properties: nil)
  # Add additional model properties to the instance
  additional_properties = {} if additional_properties.nil?

  @weight_uom = weight_uom unless weight_uom == SKIP
  @weight = weight
  @dimensions_uom = dimensions_uom unless dimensions_uom == SKIP
  @length = length
  @height = height
  @width = width
  @girth = girth unless girth == SKIP
  unless has_nonstandard_characteristics == SKIP
    @has_nonstandard_characteristics =
      has_nonstandard_characteristics
  end
  @mail_class = mail_class
  @processing_category = processing_category
  @customer_reference = customer_reference unless customer_reference == SKIP
  @extra_services = extra_services unless extra_services == SKIP
  @package_options = package_options unless package_options == SKIP
  unless destination_entry_facility_address == SKIP
    @destination_entry_facility_address =
      destination_entry_facility_address
  end
  @induction_zip_code = induction_zip_code unless induction_zip_code == SKIP
  unless shipper_visibility_method == SKIP
    @shipper_visibility_method =
      shipper_visibility_method
  end
  @additional_properties = additional_properties
end

Instance Attribute Details

#customer_reference ⇒ Array[LabelsCustomerReference]

Used for shippers to print a value on a label and included in the Shipping Services Files.

Returns:



106
107
108
 
# File 'lib/usps_api/models/returns_package.rb', line 106

def customer_reference
  @customer_reference
end

#destination_entry_facility_address ⇒ InternationalLabelsDomesticAddress

Destination entry facility address

Returns:



185
186
187
 
# File 'lib/usps_api/models/returns_package.rb', line 185

def destination_entry_facility_address
  @destination_entry_facility_address
end

#dimensions_uom ⇒ DimensionsUom

Dimensions unit of measure

  • in - Inches

Returns:



25
26
27
 
# File 'lib/usps_api/models/returns_package.rb', line 25

def dimensions_uom
  @dimensions_uom
end

#extra_services ⇒ Array[LabelsExtraServiceCodes]

Extra Service Code requested.

  • 365 - Global Direct Entry

  • 415 - USPS Label Delivery

  • 480 - Tracking Plus 6 Months

  • 481 - Tracking Plus 1 Year

  • 482 - Tracking Plus 3 Years

  • 483 - Tracking Plus 5 Years

  • 484 - Tracking Plus 7 Years

  • 485 - Tracking Plus 10 Years

  • 486 - Tracking Plus Signature 3 Years

  • 487 - Tracking Plus Signature 5 Years

  • 488 - Tracking Plus Signature 7 Years

  • 489 - Tracking Plus Signature 10 Years

  • 810 - HAZMAT Air Eligible Ethanol Package

  • 811 - HAZMAT Class 1 - Toy Propellant/Safety Fuse Package

  • 812 - HAZMAT Class 3 – Flammable Liquid Package

  • 813 - HAZMAT Class 7 - Radioactive Materials Package

  • 814 - HAZMAT Class 8 - Corrosive Materials Package

  • 815 - HAZMAT Class 8 - Nonspillable Wet Battery Package

  • 816 - HAZMAT Class 9 - Lithium Battery Marked - Ground Only Package

  • 817 - HAZMAT Class 9 - Lithium Battery - Returns Package

  • 818 - HAZMAT Class 9 - Lithium batteries, marked package

  • 819 - HAZMAT Class 9 - Dry Ice Package

  • 820 - HAZMAT Class 9 - Lithium batteries, unmarked package

  • 821 - HAZMAT Class 9 - Magnetized Materials Package

  • 822 - HAZMAT Division 4.1 – Flammable Solids or Safety Matches Package

  • 823 - HAZMAT Division 5.1 - Oxidizers Package

  • 824 - HAZMAT Division 5.2 - Organic Peroxides Package

  • 825 - HAZMAT Division 6.1 – Toxic Materials Package

  • 826 - HAZMAT Division 6.2 – Infectious Substances Package

  • 827 - HAZMAT Excepted Quantity Provision Package

  • 828 - HAZMAT Ground Only

  • 829 - HAZMAT ID8000 Consumer Commodity Package

  • 830 - HAZMAT Lighters Package

  • 831 - HAZMAT LTD QTY Ground Package

  • 832 - HAZMAT Small Quantity Provision Package

  • 857 - Hazardous Material

  • 910 - Certified Mail

  • 911 - Certified Mail Restricted Delivery

  • 912 - Certified Mail Adult Signature Required

  • 913 - Certified Mail Adult Signature Restricted Delivery

  • 920 - USPS Tracking

  • 921 - Signature Confirmation

  • 922 - Adult Signature Required 21 or Over

  • 923 - Adult Signature Restricted Delivery 21 or Over

  • 924 - Signature Confirmation Restricted Delivery

  • 925 - Priority Mail Express Merchandise Insurance

  • 930 - Insurance <= $500

  • 931 - Insurance > $500

  • 934 - Insurance Restricted Delivery

  • 955 - Return Receipt

  • 957 - Return Receipt Electronic

  • 981 - Signature Requested (PRIORITY_MAIL_EXPRESS only)

  • 986 - PO to Addressee (PRIORITY_MAIL_EXPRESS only)

  • 991 - Sunday Delivery

Note:

* When the extra service code "930" is provided in the request, if the

item value is over $500, “930” will automatically be replaced with “931” - Insurance (Greater than $500).

* USPS Label Delivery (Extra Service Code "415"): When requesting this

service, no images will be returned in the API response. The label and receipt will be printed and mailed to the ‘fromAddress` provided. The mailed label will always include a receipt on the page. This service is not available at all locations.

* Some service codes require a combination with extra services such as

“955” and “957”. For all valid combinations, visit [postalpro.usps.com/IMPB_Service_Type_Codes](https://postalpro.usp s.com/IMPB_Service_Type_Codes).

Returns:



177
178
179
 
# File 'lib/usps_api/models/returns_package.rb', line 177

def extra_services
  @extra_services
end

#girth ⇒ Float

The girth of the container, in dimensionsUOM. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non- rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages.

Returns:

  • (Float) 


69
70
71
 
# File 'lib/usps_api/models/returns_package.rb', line 69

def girth
  @girth
end

#has_nonstandard_characteristics ⇒ TrueClass | FalseClass

Package is nonstandard. Nonstandard packages include cylindrical tubes and rolls, certain high-density items, cartons containing more than 24 ounces of liquids in one or more glass containers, cartons containing 1 gallon or more of liquid in metal or plastic containers, and items in [201.7.6.2](pe.usps.com/text/dmm300/201.htm#7.6.2).

Returns:

  • (TrueClass | FalseClass) 


77
78
79
 
# File 'lib/usps_api/models/returns_package.rb', line 77

def has_nonstandard_characteristics
  @has_nonstandard_characteristics
end

#height ⇒ Float

The height of the container, in dimensionsUOM. If partial dimensions are provided, an error response will return. Length, Width, and Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. Girth is required only for a non-rectangular package in addition to Length, Width, and Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages.

Returns:

  • (Float) 


47
48
49
 
# File 'lib/usps_api/models/returns_package.rb', line 47

def height
  @height
end

#induction_zip_code ⇒ String

The 5-Digit ZIP Code representing the location where the package is being inducted (i.e. dropped off) into the mailstream. When provided, this ZIP Code will be used for pricing instead of ‘fromAddress.ZIPCode`.

Returns:

  • (String) 


191
192
193
 
# File 'lib/usps_api/models/returns_package.rb', line 191

def induction_zip_code
  @induction_zip_code
end

#length ⇒ Float

The length of the container, in dimensionsUOM. If partial dimensions are provided, an error response will return. Length, Width, and Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. Girth is required only for a non-rectangular package in addition to Length, Width, and Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages.

Returns:

  • (Float) 


36
37
38
 
# File 'lib/usps_api/models/returns_package.rb', line 36

def length
  @length
end

#mail_class ⇒ MailClass11

The mail service requested. Note:

  • ‘FIRST-CLASS_PACKAGE_RETURN_SERVICE` is deprecated and will convert to

‘USPS_GROUND_ADVANTAGE_RETURN_SERVICE`

  • ‘GROUND_RETURN_SERVICE` is deprecated and will convert to

‘USPS_GROUND_ADVANTAGE_RETURN_SERVICE`

Returns:



86
87
88
 
# File 'lib/usps_api/models/returns_package.rb', line 86

def mail_class
  @mail_class
end

#package_options ⇒ LabelsPackageOptions1

Options added to packages that are less frequently used

Returns:



181
182
183
 
# File 'lib/usps_api/models/returns_package.rb', line 181

def package_options
  @package_options
end

#processing_category ⇒ ProcessingCategory3

Value designates if the shipment is ‘MACHINABLE`, `NONSTANDARD`, `LETTERS`, or `FLATS`. Note:

  • The processing category ‘LETTERS` is only valid when the mail class is

‘PRIORITY_MAIL_RETURN_SERVICE` or `PRIORITY_MAIL_EXPRESS_RETURN_SERVICE` for returns shipments.

  • The processing category ‘FLATS` is not valid for mail class

‘USPS_GROUND_ADVANTAGE_RETURN_SERVICE`.

  • ‘IRREGULAR` is deprecated and will convert to `NONSTANDARD` as of

01/19/2025.

  • ‘NON_MACHINABLE` is deprecated and will convert to `NONSTANDARD` as of

01/19/2025.

Returns:



101
102
103
 
# File 'lib/usps_api/models/returns_package.rb', line 101

def processing_category
  @processing_category
end

#shipper_visibility_method ⇒ ShipperVisibilityMethod1

When generating labels for a third party shipper the label provider must capture and provide contact details of the individual or entity to whom they provide the label. For return labels, there is one method for reporting shipper information to USPS:

  1. An alternative method allows for the label provider to assign a unique

alphanumeric value known as a ‘platformUserId` to each shipper and to report the `platformUserId` together with the required shipper contact details. When using this method the shipper contact details are required in the `senderAddress` object (including `streetAddress`, `city`, `state`, `ZIPCode`, `phone`, `email`, `platformUserId` & `firstName`/`lastName` or `firm`) and this field should be populated with ’SENDER_INFORMATION’.

Returns:



205
206
207
 
# File 'lib/usps_api/models/returns_package.rb', line 205

def shipper_visibility_method
  @shipper_visibility_method
end

#weight ⇒ Float

The package weight, in weightUOM (Unit Of Measure). Items must weigh 70 pounds (1120 ounces) or less.

Returns:

  • (Float) 


20
21
22
 
# File 'lib/usps_api/models/returns_package.rb', line 20

def weight
  @weight
end

#weight_uom ⇒ WeightUom

Weight Unit of Measurement

* lb - Pounds

Returns:



15
16
17
 
# File 'lib/usps_api/models/returns_package.rb', line 15

def weight_uom
  @weight_uom
end

#width ⇒ Float

The width of the container, in dimensionsUOM. If partial dimensions are provided, an error response will return. Length, Width, and Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. Girth is required only for a non-rectangular package in addition to Length, Width, and Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages.

Returns:

  • (Float) 


58
59
60
 
# File 'lib/usps_api/models/returns_package.rb', line 58

def width
  @width
end

Class Method Details

.from_hash(hash) ⇒ Object

Creates an instance of the object from a hash.



293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
 
# File 'lib/usps_api/models/returns_package.rb', line 293

def self.from_hash(hash)
  return nil unless hash

  # Extract variables from the hash.
  weight = hash.key?('weight') ? hash['weight'] : nil
  length = hash.key?('length') ? hash['length'] : nil
  height = hash.key?('height') ? hash['height'] : nil
  width = hash.key?('width') ? hash['width'] : nil
  mail_class = hash.key?('mailClass') ? hash['mailClass'] : nil
  processing_category =
    hash.key?('processingCategory') ? hash['processingCategory'] : nil
  weight_uom = hash['weightUOM'] ||= WeightUom::LB
  dimensions_uom = hash['dimensionsUOM'] ||= DimensionsUom::ENUM_IN
  girth = hash.key?('girth') ? hash['girth'] : SKIP
  has_nonstandard_characteristics =
    hash['hasNonstandardCharacteristics'] ||= false
  # Parameter is an array, so we need to iterate through it
  customer_reference = nil
  unless hash['customerReference'].nil?
    customer_reference = []
    hash['customerReference'].each do |structure|
      customer_reference << (LabelsCustomerReference.from_hash(structure) if structure)
    end
  end

  customer_reference = SKIP unless hash.key?('customerReference')
  extra_services = hash.key?('extraServices') ? hash['extraServices'] : SKIP
  package_options = LabelsPackageOptions1.from_hash(hash['packageOptions']) if
    hash['packageOptions']
  if hash['destinationEntryFacilityAddress']
    destination_entry_facility_address = InternationalLabelsDomesticAddress.from_hash(hash['destinationEntryFacilityAddress'])
  end
  induction_zip_code =
    hash.key?('inductionZIPCode') ? hash['inductionZIPCode'] : SKIP
  shipper_visibility_method =
    hash.key?('shipperVisibilityMethod') ? hash['shipperVisibilityMethod'] : SKIP

  # Create a new hash for additional properties, removing known properties.
  new_hash = hash.reject { |k, _| names.value?(k) }

  additional_properties = APIHelper.get_additional_properties(
    new_hash, proc { |value| value }
  )

  # Create object from extracted values.
  ReturnsPackage.new(weight: weight,
                     length: length,
                     height: height,
                     width: width,
                     mail_class: mail_class,
                     processing_category: processing_category,
                     weight_uom: weight_uom,
                     dimensions_uom: dimensions_uom,
                     girth: girth,
                     has_nonstandard_characteristics: has_nonstandard_characteristics,
                     customer_reference: customer_reference,
                     extra_services: extra_services,
                     package_options: package_options,
                     destination_entry_facility_address: destination_entry_facility_address,
                     induction_zip_code: induction_zip_code,
                     shipper_visibility_method: shipper_visibility_method,
                     additional_properties: additional_properties)
end

.names ⇒ Object

A mapping from model property names to API property names.



208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/usps_api/models/returns_package.rb', line 208

def self.names
  @_hash = {} if @_hash.nil?
  @_hash['weight_uom'] = 'weightUOM'
  @_hash['weight'] = 'weight'
  @_hash['dimensions_uom'] = 'dimensionsUOM'
  @_hash['length'] = 'length'
  @_hash['height'] = 'height'
  @_hash['width'] = 'width'
  @_hash['girth'] = 'girth'
  @_hash['has_nonstandard_characteristics'] =
    'hasNonstandardCharacteristics'
  @_hash['mail_class'] = 'mailClass'
  @_hash['processing_category'] = 'processingCategory'
  @_hash['customer_reference'] = 'customerReference'
  @_hash['extra_services'] = 'extraServices'
  @_hash['package_options'] = 'packageOptions'
  @_hash['destination_entry_facility_address'] =
    'destinationEntryFacilityAddress'
  @_hash['induction_zip_code'] = 'inductionZIPCode'
  @_hash['shipper_visibility_method'] = 'shipperVisibilityMethod'
  @_hash
end

.nullables ⇒ Object

An array for nullable fields



248
249
250
 
# File 'lib/usps_api/models/returns_package.rb', line 248

def self.nullables
  []
end

.optionals ⇒ Object

An array for optional fields



232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/usps_api/models/returns_package.rb', line 232

def self.optionals
  %w[
    weight_uom
    dimensions_uom
    girth
    has_nonstandard_characteristics
    customer_reference
    extra_services
    package_options
    destination_entry_facility_address
    induction_zip_code
    shipper_visibility_method
  ]
end

Instance Method Details

#inspect ⇒ Object

Provides a debugging-friendly string with detailed object information.



372
373
374
375
376
377
378
379
380
381
382
383
384
 
# File 'lib/usps_api/models/returns_package.rb', line 372

def inspect
  class_name = self.class.name.split('::').last
  "<#{class_name} weight_uom: #{@weight_uom.inspect}, weight: #{@weight.inspect},"\
  " dimensions_uom: #{@dimensions_uom.inspect}, length: #{@length.inspect}, height:"\
  " #{@height.inspect}, width: #{@width.inspect}, girth: #{@girth.inspect},"\
  " has_nonstandard_characteristics: #{@has_nonstandard_characteristics.inspect}, mail_class:"\
  " #{@mail_class.inspect}, processing_category: #{@processing_category.inspect},"\
  " customer_reference: #{@customer_reference.inspect}, extra_services:"\
  " #{@extra_services.inspect}, package_options: #{@package_options.inspect},"\
  " destination_entry_facility_address: #{@destination_entry_facility_address.inspect},"\
  " induction_zip_code: #{@induction_zip_code.inspect}, shipper_visibility_method:"\
  " #{@shipper_visibility_method.inspect}, additional_properties: #{@additional_properties}>"
end

#to_s ⇒ Object

Provides a human-readable string representation of the object.



358
359
360
361
362
363
364
365
366
367
368
369
 
# File 'lib/usps_api/models/returns_package.rb', line 358

def to_s
  class_name = self.class.name.split('::').last
  "<#{class_name} weight_uom: #{@weight_uom}, weight: #{@weight}, dimensions_uom:"\
  " #{@dimensions_uom}, length: #{@length}, height: #{@height}, width: #{@width}, girth:"\
  " #{@girth}, has_nonstandard_characteristics: #{@has_nonstandard_characteristics},"\
  " mail_class: #{@mail_class}, processing_category: #{@processing_category},"\
  " customer_reference: #{@customer_reference}, extra_services: #{@extra_services},"\
  " package_options: #{@package_options}, destination_entry_facility_address:"\
  " #{@destination_entry_facility_address}, induction_zip_code: #{@induction_zip_code},"\
  " shipper_visibility_method: #{@shipper_visibility_method}, additional_properties:"\
  " #{@additional_properties}>"
end