Module: Usps::Api::Endpoints::IntlRateV2

Included in:: Usps::Api::Endpoints

Defined in:: lib/usps/api/endpoints/intl_rate_v2.rb

Instance Method Summary collapse

#intl_rate_v2(options = {}) ⇒ Object

The IntlRateV2 API lets customers calculate the rate for international packages and envelopes given the weight and dimensions of the item.

Instance Method Details

#intl_rate_v2(options = {}) ⇒ `Object`

The IntlRateV2 API lets customers calculate the rate for international packages and envelopes given the weight and dimensions of the item. The IntlRateV2 API limits the data requested to twenty-five (25) packages per transaction. For specifications such as package dimensions, delivery information, etc, please refer to the International Mail Manual (IMM) at pe.usps.com/.

Parameters:

options (Hash) (defaults to: {})

Options Hash (options):

intl_rate_v2_request (required, Hash) —
API=IntlRateV2 This API returns the current international USPS postage corresponding to the parameters given.
- :revision (String) — Set this value to “2” to return all currently documented response fields. For example: <Revision>2</Revsion>
- :package (Hash) — Opening Package tag.
  - :id (required, NMTOKEN) — No restriction on number or type of characters provided valid XML syntax and unique to request. For example: <Package ID=“0”>…</Package>
  - :pounds (required, Integer) — Value must be numeric. Package weight generally cannot exceed 70 pounds. Maximum Decimal places are 8. Refer to the International Mail Manual (IMM) for weight requirements per country and mail service. The IMM can be found at the Postal Explorer web site. For example: <Pounds>2</Pounds> <Pounds>2.12345678</Pounds>
  - :ounces (required, Decimal) — Value must be numeric. Package weight generally cannot exceed 70 pounds. Maximum Decimal places are 8. Refer to the International Mail Manual (IMM) for weight requirements per country and mail service. The IMM can be found at the Postal Explorer web site. For example: <Ounces>4</Ounces> <Ounces>4.12345678</Ounces>
  - :machinable (Boolean) — Indicates whether or not the item is machinable. A surcharge is applied to a First-Class Mail International item if it has one or more non-machinable characteristics. See International Mail Manual (IMM) Section 241.217 for more information. For example: <Machinable>True</Machinable>
  - :mail_type (required, String) — Package type being shipped. For example: <MailType>Package</MailType> Note: Airmail M-Bag prices will return for retail pricing when available including when <MailType>=“ALL.” Reference pe.usps.com/text/imm/immc2_026.htm for M-Bag pricing details. Note: When <MailType>= “ALL” is indicated in XML request and a <TrackingRetentionPeriod> value is not specified, the lowest tracking retention period values (i.e., “0.5” (6 months) for ServiceID=“181” and “3” (3 years) for ServiceID=“182”) will be used to return available USPS Tracking Plus extra service options for supported mail services.
  - :gxg (Hash) — If GXG rate is desired, then this group must be specified. Note that if this data precludes delivery, due to size or availability of service at the destination, then GXG rates simply will not be returned (not an error condition.)
    - :po_box_flag (required, String) — Specify as “Y” if the destination is a post office box. For example: <POBoxFlag>Y</POBoxFlag>
    - :gift_flag (required, String) — Specify as “Y” if the package contains a gift. For example: <GiftFlag>Y</GiftFlag>
    - :value_of_contents (required, String) — If specified, used to compute Insurance fee (if insurance is available for service and destination). For example: <ValueOfContents>103.00</ValueOfContents>
    - :country (required, String) — Entries must be from the USPS list of valid countries from the International Country Listings. To access the International Country Listings, go to the Index of Countries and Localities. For example: <Country>Albania</Country>
    - :container (String) — Used to specify a container. When package is a roll, integrators should pass <Container>= “ROLL” in XML request. If package is not a roll, integrators should not populate – label response will assume package is not a roll. Note: When <Container>= “ROLL”, errors will return if dimensions provided in XML request do not meet IMM 251.22 requirements. pe.usps.com/text/imm/immc2_021.htm.
    - :size (String) — Note: This tag has been deprecated <Size> tag and any values within the <Size> tag will not result in an error response and will not impact rates that are returned.
    - :width (Integer) — Value must be numeric. Units are inches. 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. For more details on dimensional weight pricing or dimension validation reference IMM pe.usps.com/text/imm/welcome.htm
    - :length (Integer) — Value must be numeric. Units are inches. 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. For more details on dimensional weight pricing or dimension validation reference IMM pe.usps.com/text/imm/welcome.htm
    - :height (Integer) — Value must be numeric. Units are inches. 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. For more details on dimensional weight pricing or dimension validation reference IMM pe.usps.com/text/imm/welcome.htm
    - :girth (Integer) — Value must be numeric. Units are inches. 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. For more details on dimensional weight pricing or dimension validation reference IMM pe.usps.com/text/imm/welcome.htm
    - :origin_zip (String) — Available when Revision= “2”. Origin ZIP Code is required to determine Priority Mail International price to Canadian destinations and is used to determine mail-ability of Global Express Guaranteed. When provided, the response will return a list of Post Office locations where GXG is accepted. The Origin ZIP Code must be valid. For example: <OriginZip>20770</OriginZip>
    - :commercial_flag (String) — Returns commercial base postage. For example: <CommercialFlag>Y<CommercialFlag>
    - :commercial_plus_flag (String) — Returns commercial plus postage. For example: <CommercialPlusFlag>Y<CommercialPlusFlag>
    - :extra_services (Hash) — Available when IntlRateV2Request. Groups the ExtraService elements.
      
      :extra_service (Extra Service Name) — [Service Name”=>“Registered Mail”, “ServiceID”=>“103”, Service Name”=>“Insurance – Global Express Guaranteed”, “ServiceID”=>“106”, Service Name”=>“Insurance – Priority Mail International”, “ServiceID”=>“108”, Service Name”=>“Return Receipt”, “ServiceID”=>“105”, Service Name”=>“Certificate of Mailing”, “ServiceID”=>“100”, Service Name”=>“Electronic USPS Delivery Confirmation International”, “ServiceID”=>“109”, Service Name”=>“Scan Retention”, “ServiceID”=>“181”, Service Name”=>“Scan + Signature Retention”, “ServiceID”=>“182”]
      
      :acceptance_date_time (DateTime) — Available when IntlRateV2Request. Date and Time the package is accepted by USPS. The AcceptanceDateTime tag along with the DestinationPostalCode and OriginZip is used to calculate the GuaranteeAvailability and also GuaranteeAvailability response tag for PMEI services in Kahala countries. ISO 8601 formatted date. YYYY-MM-DDThh:mm:ss+/-hh:mm For example, 2014-01-22T14:30:51-06:00
      
      :destination_postal_code (String) — Available when IntlRateV2Request. Destination Postal Code The AcceptanceDateTime tag along with the DestinationPostalCode and OriginZip is used to calculate the GuaranteeAvailability and also GuaranteeAvailability response tag for PMEI services in Kahala countries.
      
      :content (Hash) — Used to describe the contents of the package.
      
      :content_type (String) — Contains the enumerated description of the items in the package. “NonnegotiableDocument” and “Documents” both signify mailable non-negotiable documents and are insured automatically for up to $100, though Insurance will not be returned as an extra service. Additional Insurance cannot be purchased. Any non-document ContentType values are insured automatically for up to $200 and Insurance will be returned as an explicit extra service in the response. Additional Insurance can be purchased for values $200 and greater.
      
      :content_description (String) — For future use
      
      :tracking_retention_period (ServiceID) — [“<TrackingRetentionPeriod>”=>““0.5” (6 Months)”, “<TrackingRetentionPeriod>”=>““1” (1 Year)”, “<TrackingRetentionPeriod>”=>““3” (3 Years)”, “<TrackingRetentionPeriod>”=>““5” (5 Years)”, “<TrackingRetentionPeriod>”=>““7” (7 Years)”, “<TrackingRetentionPeriod>”=>““3” (3 Years)”, “<TrackingRetentionPeriod>”=>““5” (5 Years)”, “<TrackingRetentionPeriod>”=>““7” (7 Years)”]

# File 'lib/usps/api/endpoints/intl_rate_v2.rb', line 46

def intl_rate_v2(options = {})
	throw ArgumentError.new('Required arguments :intl_rate_v2_request missing') if options[:intl_rate_v2_request].nil?

	request = build_request(:intl_rate_v2, options)
	get('https://secure.shippingapis.com/ShippingAPI.dll', {
		API: 'IntlRateV2',
		XML: request,
	})
end

Module: Usps::Api::Endpoints::IntlRateV2

Instance Method Summary collapse

Instance Method Details

#intl_rate_v2(options = {}) ⇒ Object

#intl_rate_v2(options = {}) ⇒ `Object`