Class: UspsApi::PackageOptions

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

Overview

PackageOptions 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(package_value: SKIP, non_delivery_option: SKIP, omas: SKIP, redirect_address: SKIP, content_type: SKIP, generate_gx_event: true, containers: SKIP, ancillary_service_endorsements: SKIP, return_receipt_tracking: false, immediate_manifest: false, original_package: SKIP, additional_properties: nil) ⇒ PackageOptions

Returns a new instance of PackageOptions.



192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/usps_api/models/package_options.rb', line 192

def initialize(package_value: SKIP, non_delivery_option: SKIP, omas: SKIP,
               redirect_address: SKIP, content_type: SKIP,
               generate_gx_event: true, containers: SKIP,
               ancillary_service_endorsements: SKIP,
               return_receipt_tracking: false, immediate_manifest: false,
               original_package: SKIP, additional_properties: nil)
  # Add additional model properties to the instance
  additional_properties = {} if additional_properties.nil?

  @package_value = package_value unless package_value == SKIP
  @non_delivery_option = non_delivery_option unless non_delivery_option == SKIP
  @omas = omas unless omas == SKIP
  @redirect_address = redirect_address unless redirect_address == SKIP
  @content_type = content_type unless content_type == SKIP
  @generate_gx_event = generate_gx_event unless generate_gx_event == SKIP
  @containers = containers unless containers == SKIP
  unless ancillary_service_endorsements == SKIP
    @ancillary_service_endorsements =
      ancillary_service_endorsements
  end
  @return_receipt_tracking = return_receipt_tracking unless return_receipt_tracking == SKIP
  @immediate_manifest = immediate_manifest unless immediate_manifest == SKIP
  @original_package = original_package unless original_package == SKIP
  @additional_properties = additional_properties
end

Instance Attribute Details

#ancillary_service_endorsements ⇒ AncillaryServiceEndorsements

Endorsements allow the sender to obtain the addressee’s new (forwarding) address (provided the appropriate endorsement is used and if the addressee filed a

Change-of-Address Order with the Postal Service) or the reason for non-delivery. For more information see [PostalPro](postalpro.usps.com/address-quality/ancillary-service-e ndorsements). Note:

* Ancillary Service Endorsements are currently not supported when

‘holdForPickup’ is set to ‘true’.

* 'CHANGE_SERVICE_REQUESTED' with a mail class value of 'PRIORITY_MAIL'

currently only supports a contentType of ‘PERISHABLE’.

* 'CHANGE_SERVICE_REQUESTED' cannot be requested with a 'contentType' of

‘HAZMAT’ or any hazmat shipments.

* 'CHANGE_SERVICE_REQUESTED' with mail classes 'PARCEL_SELECT',

‘USPS_GROUND_ADVANTAGE’, and ‘PRIORITY_MAIL’ can only be used with extraServices ‘920’ and ‘921’.

* Ancillary Service Endorsements are currently only supported with mail

class values ‘PARCEL_SELECT’, ‘USPS_GROUND_ADVANTAGE’, ‘PRIORITY_MAIL’, and ‘PRIORITY_MAIL_EXPRESS’.

* 'ELECTRONIC_SERVICE_REQUESTED' with a mail class value of

‘PARCEL_SELECT’ cannot be requested with a ‘contentType’ of ‘HAZMAT’ or any hazmat shipments.

Returns:



121
122
123
 
# File 'lib/usps_api/models/package_options.rb', line 121

def ancillary_service_endorsements
  @ancillary_service_endorsements
end

#containers ⇒ Array[LabelsContainer]

containers

Returns:



93
94
95
 
# File 'lib/usps_api/models/package_options.rb', line 93

def containers
  @containers
end

#content_type ⇒ ContentType

The type of contents in the package. Note:

  • ‘CREMATED_REMAINS` is currently only eligible for the

‘PRIORITY_MAIL_EXPRESS` mail class and is not eligible for Hold for Pickup shipments. Please refer to [Publication 139](about.usps.com/publications/pub139/welcome.htm) for guidelines on how to package and ship `CREMATED_REMAINS`.

  • ‘DAY_OLD_POULTRY` is currently only eligible with mail class values of

‘USPS_GROUND_ADVANTAGE`, `PRIORITY_MAIL` and `PRIORITY_MAIL_EXPRESS`.

  • Shipments that contain Live Animals or Perishables will incur a Live

Animal and Perishables Handling Fee per mail piece. Content types ‘HAZMAT`, `CREMATED_REMAINS`, and `MEDICAL_SUPPLIES` do not apply and will not incur a fee. For `DAY_OLD_POULTRY` shipments only, an additional Live Animal Transport Fee per pound is applied. For more information, please visit [Live Animals Transportation Fee FAQ](faq.usps.com/s/article/Live-Animal-Transportation-Fee#:~:text

The%20Live%20Animal%20Transportation%20fee%20is%20charged%20%240.20%20per

%20pound,prices%20to%20Zones%205%2D9)

  • ‘HAZMAT` domestic labels with destination addresses to APO/FPO/DPO and

PTFAS (except Puerto Rico) will not contain any Hazmat markings/indicators, including service type codes in the IMpb. When users indicate a shipment contains hazmat materials in the API request (via content type and/or extra services), that information will still be captured and sent in the shipping services file. For more information, please review the [USPS APIs release notes](postalpro.usps.gov/usps-apis-releases)

  • For guidelines on shipping Perishable and Hazardous Material, please

refer to [Publication 52](pe.usps.com/text/pub52/welcome.htm).

  • For ZIP codes with restrictions:

    • Please refer to the most recent [Postal

Bulletin](about.usps.com/resources/postal-bulletin.htm) ZIP restriction table for more information. You can find this data under ‘Pull-Out information` -> `Other Information` -> `Overseas Military/Diplomatic Mail`.

* When restriction `M` applies, then `BEES`, `DAY_OLD_POULTRY`,

‘ADULT_BIRDS`, `OTHER_LIVES`, `FRUITS`, `VEGETABLES`, and `LIVE_PLANTS` are not allowed.

* When restriction `X` applies, then `CREMATED_REMAINS` are not allowed.

Returns:



84
85
86
 
# File 'lib/usps_api/models/package_options.rb', line 84

def content_type
  @content_type
end

#generate_gx_event ⇒ TrueClass | FalseClass

Provides the option for a user to not create a “GX” event for the package. By default, a GX event will be created.

Returns:

  • (TrueClass | FalseClass) 


89
90
91
 
# File 'lib/usps_api/models/package_options.rb', line 89

def generate_gx_event
  @generate_gx_event
end

#immediate_manifest ⇒ TrueClass | FalseClass

Setting this field to ‘true` will send electronic data to Postal systems within 15 minutes of label creation. If invoked, this label <u><strong>cannot</strong></u> be canceled. Instead, one must request an unused label refund – which may be subject to an admin fee.

Depending on time of label creation, your packages could be charged same day instead of next day.

Returns:

  • (TrueClass | FalseClass) 


145
146
147
 
# File 'lib/usps_api/models/package_options.rb', line 145

def immediate_manifest
  @immediate_manifest
end

#non_delivery_option ⇒ NonDeliveryOption

Requested action in the case a package is undeliverable:

- `RETURN` for package to be returned to `fromAddress`.
- `REDIRECT` to return package to address specified in the

‘redirectAddress`.

- `ABANDON` to dispose of undeliverable package

Note:

* `REDIRECT` and `ABANDON` will not impact the domestic package

endpoint. Please use ancillary service endorsements instead.

* An address must be provided in `redirectAddress` when a value of

‘REDIRECT` is provided.

Returns:



33
34
35
 
# File 'lib/usps_api/models/package_options.rb', line 33

def non_delivery_option
  @non_delivery_option
end

#omas ⇒ Omas

Fields specific to Official Mail Accounting System (OMAS). Used for Federal Agencies.

Returns:



38
39
40
 
# File 'lib/usps_api/models/package_options.rb', line 38

def omas
  @omas
end

#original_package ⇒ OriginalPackage1

  • Note: packageOptions.originalPackage fields cannot be used in

combination with packageOptions.returnReceiptTracking.

Returns:



150
151
152
 
# File 'lib/usps_api/models/package_options.rb', line 150

def original_package
  @original_package
end

#package_value ⇒ Float

The merchandise value of the package, in US dollars. Used to calculate Insurance Fees if requested. Note:

* Requires extraServiceCode 910, 911, 912, 913, 921, 922, 923, 924, 925,

934, 955, 981 or extraServiceCode 930 with a packageValue greater than 500

* Package value is required when an 'extraServiceCode' value of '930' is

provided.

Returns:

  • (Float) 


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

def package_value
  @package_value
end

#redirect_address ⇒ InternationalLabelsDomesticLabelAddress

Fields specific to Official Mail Accounting System (OMAS). Used for Federal Agencies.

Returns:



43
44
45
 
# File 'lib/usps_api/models/package_options.rb', line 43

def redirect_address
  @redirect_address
end

#return_receipt_tracking ⇒ TrueClass | FalseClass

Indicates whether a return receipt tracking number should be generated for the package. If set to ‘true`, the system will automatically add the Extra Service Code (ESC) `955` if it is not already present. When enabled, the `returnReceiptTrackingNumber` field will be populated in the response. Note:

* `returnReceiptTracking` cannot be used in combination with

‘packageOptions.originalPackage` fields.

* Utilizing `returnReceiptTracking` will incur the `955` ESC associated

fee.

Returns:

  • (TrueClass | FalseClass) 


135
136
137
 
# File 'lib/usps_api/models/package_options.rb', line 135

def return_receipt_tracking
  @return_receipt_tracking
end

Class Method Details

.from_hash(hash) ⇒ Object

Creates an instance of the object from a hash.



219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/usps_api/models/package_options.rb', line 219

def self.from_hash(hash)
  return nil unless hash

  # Extract variables from the hash.
  package_value = hash.key?('packageValue') ? hash['packageValue'] : SKIP
  non_delivery_option =
    hash.key?('nonDeliveryOption') ? hash['nonDeliveryOption'] : SKIP
  omas = Omas.from_hash(hash['omas']) if hash['omas']
  if hash['redirectAddress']
    redirect_address = InternationalLabelsDomesticLabelAddress.from_hash(hash['redirectAddress'])
  end
  content_type = hash.key?('contentType') ? hash['contentType'] : SKIP
  generate_gx_event = hash['generateGXEvent'] ||= true
  # Parameter is an array, so we need to iterate through it
  containers = nil
  unless hash['containers'].nil?
    containers = []
    hash['containers'].each do |structure|
      containers << (LabelsContainer.from_hash(structure) if structure)
    end
  end

  containers = SKIP unless hash.key?('containers')
  ancillary_service_endorsements =
    hash.key?('ancillaryServiceEndorsements') ? hash['ancillaryServiceEndorsements'] : SKIP
  return_receipt_tracking = hash['returnReceiptTracking'] ||= false
  immediate_manifest = hash['immediateManifest'] ||= false
  original_package = OriginalPackage1.from_hash(hash['originalPackage']) if
    hash['originalPackage']

  # 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.
  PackageOptions.new(package_value: package_value,
                     non_delivery_option: non_delivery_option,
                     omas: omas,
                     redirect_address: redirect_address,
                     content_type: content_type,
                     generate_gx_event: generate_gx_event,
                     containers: containers,
                     ancillary_service_endorsements: ancillary_service_endorsements,
                     return_receipt_tracking: return_receipt_tracking,
                     immediate_manifest: immediate_manifest,
                     original_package: original_package,
                     additional_properties: additional_properties)
end

.names ⇒ Object

A mapping from model property names to API property names.



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/usps_api/models/package_options.rb', line 153

def self.names
  @_hash = {} if @_hash.nil?
  @_hash['package_value'] = 'packageValue'
  @_hash['non_delivery_option'] = 'nonDeliveryOption'
  @_hash['omas'] = 'omas'
  @_hash['redirect_address'] = 'redirectAddress'
  @_hash['content_type'] = 'contentType'
  @_hash['generate_gx_event'] = 'generateGXEvent'
  @_hash['containers'] = 'containers'
  @_hash['ancillary_service_endorsements'] =
    'ancillaryServiceEndorsements'
  @_hash['return_receipt_tracking'] = 'returnReceiptTracking'
  @_hash['immediate_manifest'] = 'immediateManifest'
  @_hash['original_package'] = 'originalPackage'
  @_hash
end

.nullables ⇒ Object

An array for nullable fields



188
189
190
 
# File 'lib/usps_api/models/package_options.rb', line 188

def self.nullables
  []
end

.optionals ⇒ Object

An array for optional fields



171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/usps_api/models/package_options.rb', line 171

def self.optionals
  %w[
    package_value
    non_delivery_option
    omas
    redirect_address
    content_type
    generate_gx_event
    containers
    ancillary_service_endorsements
    return_receipt_tracking
    immediate_manifest
    original_package
  ]
end

.validate(value) ⇒ Object

Validates an instance of the object from a given value.

Parameters:

  • The (PackageOptions | Hash) —

    value against the validation is performed.



273
274
275
276
277
278
279
 
# File 'lib/usps_api/models/package_options.rb', line 273

def self.validate(value)
  return true if value.instance_of? self

  return false unless value.instance_of? Hash

  true
end

Instance Method Details

#inspect ⇒ Object

Provides a debugging-friendly string with detailed object information.



294
295
296
297
298
299
300
301
302
303
304
 
# File 'lib/usps_api/models/package_options.rb', line 294

def inspect
  class_name = self.class.name.split('::').last
  "<#{class_name} package_value: #{@package_value.inspect}, non_delivery_option:"\
  " #{@non_delivery_option.inspect}, omas: #{@omas.inspect}, redirect_address:"\
  " #{@redirect_address.inspect}, content_type: #{@content_type.inspect}, generate_gx_event:"\
  " #{@generate_gx_event.inspect}, containers: #{@containers.inspect},"\
  " ancillary_service_endorsements: #{@ancillary_service_endorsements.inspect},"\
  " return_receipt_tracking: #{@return_receipt_tracking.inspect}, immediate_manifest:"\
  " #{@immediate_manifest.inspect}, original_package: #{@original_package.inspect},"\
  " additional_properties: #{@additional_properties}>"
end

#to_s ⇒ Object

Provides a human-readable string representation of the object.



282
283
284
285
286
287
288
289
290
291
 
# File 'lib/usps_api/models/package_options.rb', line 282

def to_s
  class_name = self.class.name.split('::').last
  "<#{class_name} package_value: #{@package_value}, non_delivery_option:"\
  " #{@non_delivery_option}, omas: #{@omas}, redirect_address: #{@redirect_address},"\
  " content_type: #{@content_type}, generate_gx_event: #{@generate_gx_event}, containers:"\
  " #{@containers}, ancillary_service_endorsements: #{@ancillary_service_endorsements},"\
  " return_receipt_tracking: #{@return_receipt_tracking}, immediate_manifest:"\
  " #{@immediate_manifest}, original_package: #{@original_package}, additional_properties:"\
  " #{@additional_properties}>"
end