Class: UspsApi::LabelsImageInfo

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

Overview

Additional details used to determine how to generate the label image.

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(image_type: ImageType3::PDF, label_type: LabelType3::ENUM_4X6LABEL, ship_info: SKIP, receipt_option: ReceiptOption1::SAME_PAGE, branding_image_format: BrandingImageFormat::NONE, branding_image_uui_ds:, include_label_broker_pdf: false, add_zpl_comments: false, add_image_comments: false, additional_properties: nil) ⇒ LabelsImageInfo

Returns a new instance of LabelsImageInfo.



182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/usps_api/models/labels_image_info.rb', line 182

def initialize(image_type: ImageType3::PDF,
               label_type: LabelType3::ENUM_4X6LABEL, ship_info: SKIP,
               receipt_option: ReceiptOption1::SAME_PAGE,
               branding_image_format: BrandingImageFormat::NONE,
               branding_image_uui_ds:, include_label_broker_pdf: false,
               add_zpl_comments: false, add_image_comments: false,
               additional_properties: nil)
  # Add additional model properties to the instance
  additional_properties = {} if additional_properties.nil?

  @image_type = image_type unless image_type == SKIP
  @label_type = label_type unless label_type == SKIP
  @ship_info = ship_info unless ship_info == SKIP
  @receipt_option = receipt_option unless receipt_option == SKIP
  @branding_image_format = branding_image_format unless branding_image_format == SKIP
  @branding_image_uui_ds = branding_image_uui_ds unless branding_image_uui_ds == SKIP
  @include_label_broker_pdf = include_label_broker_pdf unless include_label_broker_pdf == SKIP
  @add_zpl_comments = add_zpl_comments unless add_zpl_comments == SKIP
  @add_image_comments = add_image_comments unless add_image_comments == SKIP
  @additional_properties = additional_properties
end

Instance Attribute Details

#add_image_comments ⇒ TrueClass | FalseClass

Applicable only when ‘imageType` is `ZPL203DPI` or `ZPL300DPI`. When `addImageComments` is `true`, comments will be visible within the ZPL text response to the user to denote different sections of their label. When `addImageComments` is `false`, no comments will be included in the ZPL text response. This will be ignored for any other `imageType`. Example of a ZPL comment: `^FX Start of label. 123e4567-e89b-12d3-a456-426614174000 ^FS`

Returns:

  • (TrueClass | FalseClass) 


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

def add_image_comments
  @add_image_comments
end

#add_zpl_comments ⇒ TrueClass | FalseClass

Note: This field has been deprecated in favor of ‘addImageComments`. Applicable only when `imageType` is `ZPL203DPI` or `ZPL300DPI`. When `addZPLComments` is `true`, comments will be visible within the ZPL text response to the user to denote different sections of their label. When `addZPLComments` is `false`, no comments will be included in the ZPL text response. This will be ignored for any other `imageType`. Example of a ZPL comment: `^FX Start of label. 123e4567-e89b-12d3-a456-426614174000 ^FS`

Returns:

  • (TrueClass | FalseClass) 


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

def add_zpl_comments
  @add_zpl_comments
end

#branding_image_format ⇒ BrandingImageFormat

The format of label branding images to be shown on the generated label image. Note:

  • Label branding images will not be shown on labels with customs forms.

  • Label branding images are not currently supported with an ‘imageType` of

‘ZPL203DPI` or `ZPL300DPI`.

  • Label branding images are not currently supported with a ‘labelType` of

‘4X4LABEL`.

  • When a ‘brandingImageFormat` is provided with a Destination Entry

Facility, the Drop-Off Location will not be displayed on the label.

  • When a ‘brandingImageFormat` of `RECTANGLE` is provided, Customer

Reference #3-#4 cannot be provided since they will not be shown.

  • When a ‘brandingImageFormat` of `ONE_SQUARE` or `TWO_SQUARES` is

provided, Customer Reference numbers will be shifted to the right to accommodate the image.

  • When a ‘brandingImageFormat` of `RECTANGLE` is provided, Customer

Reference numbers, package number, and total packages will not be displayed on the label.

  • A ‘brandingImageFormat` of `ONE_SQUARE` is currently only supported with

‘labelType` of `4X6LABEL`, `4X5LABEL`, `6X4LABEL`, and `2X7LABEL` for both outbound and return labels.

  • A ‘brandingImageFormat` of `TWO_SQUARES` is currently only supported

with ‘labelType` of `4X6LABEL`, `4X5LABEL`, and `6X4LABEL` for both outbound and return labels.

  • A ‘brandingImageFormat` of `RECTANGLE` is currently only supported with

‘labelType` of `4X6LABEL`, `4X5LABEL`, and `6X4LABEL` for outbound labels and `4X5LABEL` and `6X4LABEL` for return labels.

Returns:



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

def branding_image_format
  @branding_image_format
end

#branding_image_uui_ds ⇒ Array[String]

The UUIDs associated with custom images uploaded in the Logo Branding endpoint: /branding Note:

  • These UUIDs must have been created with the same Payment Authorization

Label Owner CRID in use when creating the label

  • When using ‘ONE_SQUARE` or `RECTANGLE` the brandingImageUUIDs list

should include only one imageUUID string.

  • When using ‘TWO_SQUARES` the brandingImageUUIDs list should include only

two imageUUID strings.

Returns:

  • (Array[String]) 


113
114
115
 
# File 'lib/usps_api/models/labels_image_info.rb', line 113

def branding_image_uui_ds
  @branding_image_uui_ds
end

#image_type ⇒ ImageType3

The type of label image requested. If omitted then the default image type is PDF.

  • ‘PDF’

  • ‘TIFF’

  • ‘JPG’

  • ‘PNG’

  • ‘GIF’

  • ‘SVG’

  • ‘ZPL203DPI’

  • ‘ZPL300DPI’

  • ‘LABEL_BROKER’ - Request a USPS QR code to allow your customers with no

access to a printer to print at participating Post Office Locations. All USPS API users and third-party integrators utilizing QR codes are subject to the [Label Broker terms and conditions](www.usps.com/terms-conditions/label-broker.htm). For more information please see the Label Broker guide available on [GitHub](github.com/USPS/api-examples/blob/main/USPS%20APIs%20Dome stic%20Labels%20API%20Documentation_2023_0901%20Published.pdf) (Note: Only supports labelType of ‘4X6LABEL’ or ‘6X4LABEL’ and receiptOption of ‘NONE’). A USPS Label Broker QR code image will be returned in the API response instead of a label image.

  • ‘NONE’

Note:

  • Labels with customs forms only support formats of ‘PDF`, `TIFF`,

‘ZPL203DPI`, `ZPL300DPI`, `LABEL_BROKER`, and `NONE`.

  • Including Extra Service Code ‘415 - USPS Label Delivery` returns no

images and is equivalent to requesting ‘NONE`.

Returns:



40
41
42
 
# File 'lib/usps_api/models/labels_image_info.rb', line 40

def image_type
  @image_type
end

#include_label_broker_pdf ⇒ TrueClass | FalseClass

Applicable only when ‘imageType` is `LABEL_BROKER`. When `includeLabelBrokerPDF` is `true`, two label images will be returned in the multi-part and vendor response as `labelBrokerQR` and `labelImage`. `labelBrokerQR` will contain the base64 PNG of the Label Broker QR Code and `labelImage` will contain the base64 PDF of the Label stored in Label Broker. When `includeLabelBrokerPDF` is `false`, one image will be returned in the multi-part and vendor response as `labelImage` as the base64 PNG of the Label Broker QR Code.

Returns:

  • (TrueClass | FalseClass) 


124
125
126
 
# File 'lib/usps_api/models/labels_image_info.rb', line 124

def include_label_broker_pdf
  @include_label_broker_pdf
end

#label_type ⇒ LabelType3

Ability to select the label image size. If omitted then the default label size is ‘4X6LABEL`. Note:

* Currently, customs forms only support `4X6LABEL`.
* The `labelType` of `2X7LABEL` is not supported with the `imageType` of

‘ZPL203DPI` or `ZPL300DPI`.

Returns:



49
50
51
 
# File 'lib/usps_api/models/labels_image_info.rb', line 49

def label_type
  @label_type
end

#receipt_option ⇒ ReceiptOption1

Label & Receipt print out options: Enter ‘SAME_PAGE` to print the Label and the Receipt on a single page. Enter `SEPARATE_PAGE` to print the Label and the Receipt on separate pages. Enter `NONE` to print the Label only and no Receipt. Note:

* The `labelType` of `4X4LABEL` or `6X4LABEL` with the image `imageType`

of ‘ZPL203DPI` or `ZPL300DPI` does not support a `receiptOption` of `SEPARATE_PAGE`.

* When `imageType` is `ZPL203DPI` or `ZPL300DPI`, a `receiptOption` of

‘SAME_PAGE` is not supported.

* When `imageType` is `ZPL203DPI` or `ZPL300DPI` and `receiptOption` is

‘SEPARATE_PAGE`, the receipt will be returned as an additional label segment within the single ZPL payload in `labelImage`. In this case, `receiptImage` will not be populated.

Returns:



71
72
73
 
# File 'lib/usps_api/models/labels_image_info.rb', line 71

def receipt_option
  @receipt_option
end

#ship_info ⇒ TrueClass | FalseClass

indicates if revenue protection information is printed on the label. (true or false)

Returns:

  • (TrueClass | FalseClass) 


54
55
56
 
# File 'lib/usps_api/models/labels_image_info.rb', line 54

def ship_info
  @ship_info
end

Class Method Details

.from_hash(hash) ⇒ Object

Creates an instance of the object from a hash.



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/usps_api/models/labels_image_info.rb', line 205

def self.from_hash(hash)
  return nil unless hash

  # Extract variables from the hash.
  image_type = hash['imageType'] ||= ImageType3::PDF
  label_type = hash['labelType'] ||= LabelType3::ENUM_4X6LABEL
  ship_info = hash.key?('shipInfo') ? hash['shipInfo'] : SKIP
  receipt_option = hash['receiptOption'] ||= ReceiptOption1::SAME_PAGE
  branding_image_format =
    hash['brandingImageFormat'] ||= BrandingImageFormat::NONE
  branding_image_uui_ds = hash['brandingImageUUIDs'] ||= 
  include_label_broker_pdf = hash['includeLabelBrokerPDF'] ||= false
  add_zpl_comments = hash['addZPLComments'] ||= false
  add_image_comments = hash['addImageComments'] ||= false

  # 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.
  LabelsImageInfo.new(image_type: image_type,
                      label_type: label_type,
                      ship_info: ship_info,
                      receipt_option: receipt_option,
                      branding_image_format: branding_image_format,
                      branding_image_uui_ds: branding_image_uui_ds,
                      include_label_broker_pdf: include_label_broker_pdf,
                      add_zpl_comments: add_zpl_comments,
                      add_image_comments: add_image_comments,
                      additional_properties: additional_properties)
end

.names ⇒ Object

A mapping from model property names to API property names.



148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/usps_api/models/labels_image_info.rb', line 148

def self.names
  @_hash = {} if @_hash.nil?
  @_hash['image_type'] = 'imageType'
  @_hash['label_type'] = 'labelType'
  @_hash['ship_info'] = 'shipInfo'
  @_hash['receipt_option'] = 'receiptOption'
  @_hash['branding_image_format'] = 'brandingImageFormat'
  @_hash['branding_image_uui_ds'] = 'brandingImageUUIDs'
  @_hash['include_label_broker_pdf'] = 'includeLabelBrokerPDF'
  @_hash['add_zpl_comments'] = 'addZPLComments'
  @_hash['add_image_comments'] = 'addImageComments'
  @_hash
end

.nullables ⇒ Object

An array for nullable fields



178
179
180
 
# File 'lib/usps_api/models/labels_image_info.rb', line 178

def self.nullables
  []
end

.optionals ⇒ Object

An array for optional fields



163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/usps_api/models/labels_image_info.rb', line 163

def self.optionals
  %w[
    image_type
    label_type
    ship_info
    receipt_option
    branding_image_format
    branding_image_uui_ds
    include_label_broker_pdf
    add_zpl_comments
    add_image_comments
  ]
end

Instance Method Details

#inspect ⇒ Object

Provides a debugging-friendly string with detailed object information.



252
253
254
255
256
257
258
259
260
261
 
# File 'lib/usps_api/models/labels_image_info.rb', line 252

def inspect
  class_name = self.class.name.split('::').last
  "<#{class_name} image_type: #{@image_type.inspect}, label_type: #{@label_type.inspect},"\
  " ship_info: #{@ship_info.inspect}, receipt_option: #{@receipt_option.inspect},"\
  " branding_image_format: #{@branding_image_format.inspect}, branding_image_uui_ds:"\
  " #{@branding_image_uui_ds.inspect}, include_label_broker_pdf:"\
  " #{@include_label_broker_pdf.inspect}, add_zpl_comments: #{@add_zpl_comments.inspect},"\
  " add_image_comments: #{@add_image_comments.inspect}, additional_properties:"\
  " #{@additional_properties}>"
end

#to_s ⇒ Object

Provides a human-readable string representation of the object.



241
242
243
244
245
246
247
248
249
 
# File 'lib/usps_api/models/labels_image_info.rb', line 241

def to_s
  class_name = self.class.name.split('::').last
  "<#{class_name} image_type: #{@image_type}, label_type: #{@label_type}, ship_info:"\
  " #{@ship_info}, receipt_option: #{@receipt_option}, branding_image_format:"\
  " #{@branding_image_format}, branding_image_uui_ds: #{@branding_image_uui_ds},"\
  " include_label_broker_pdf: #{@include_label_broker_pdf}, add_zpl_comments:"\
  " #{@add_zpl_comments}, add_image_comments: #{@add_image_comments}, additional_properties:"\
  " #{@additional_properties}>"
end