module Usps::Api::Endpoints::CarrierPickupSchedule

Public Instance Methods

carrier_pickup_schedule(options = {}) click to toggle source

The Package Pickup Schedule API schedules a Package Pickup and provides the user a confirmation number for the scheduled pickup. Prior to making a Pickup Schedule call, it is recommended to use the Pickup Availability API to confirm that service is available. @param [Hash] options @option options [required, Hash] carrier_pickup_schedule_request

* *:first_name* (required, String) — Only alpha characters, apostrophes, spaces, periods, and hyphens "-" may be used. For example: <FirstName>John</FirstName>
* *:last_name* (required, String) — Only alpha characters, apostrophes, spaces, periods and hyphens "-" may be used. For example: <LastName>Doe</LastName>
* *:firm_name* (String) — Only alpha and numeric characters, apostrophes, spaces, hyphens "-" and ampersands "&" may be used. Use this tag for a firm or company name. Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address. Note: FirmName is Optional except if the First Name and Last Name tags are null. For example: <FirmName>ABC Company</FirmName>
* *:suite_or_apt* (required, String) — Apartment or suite number. Optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building. For example: <SuiteOrApt>Suite 777</SuiteOrApt>
* *:address2* (required, String) — Street address. For example: <Address2>1390 Market Street</Address2>
* *:urbanization* (required, String) — Use this tag for Urbanization (for Puerto Rico only). ZIP Code prefixes 006 to 009, if area is so designated.
* *:city* (required, String) — City name. Either ZIP5 or City and State are required. For example: <City>Houston</City>
* *:state* (required, String) — State abbreviation. Either ZIP5 or City and State are required. For example: <State>TX</State>
* *:zip5* (required, String) — 5-digit ZIP Code. Either ZIP5 or City and State are required. For example: <ZIP5>77058</ZIP5>
* *:zip4* (required, String) — Use this tag for a 4 digit ZIP Code. For example: <ZIP4>1234</ZIP4>
* *:phone* (required, String) — Two formats are allowed: (###) 123-4567 or ###-123-4567. For example: <Phone>5555551234</Phone> or <Phone>555-555-1234</Phone>
* *:extension* (String) — Optional value for Phone Extension. For example: <Extension>201</Extension>
* *:package* (required, Hash) — No values entered with this tag. <ServiceType> and <Count> tags are embedded under this. Refer to the XML request example section, below, to see how these embedded tags are formatted. If the <Count> for a service type is zero, you do not need to encode a <Package> but you must have at least one <Package> with embedded <ServiceType> and <Count> tags.
  * *:service_type* (required, String) — This tag is embedded under the <Package> tag. If your pickup contains more than one Service Type, use additional <Package> tags for each service type with the accompanying <ServiceType> and <Count> tags. Refer to the XML Request Example below to see how these embedded tags are formatted. For example: <ServiceType>PriorityMailExpress</ServiceType>
  * *:count* (required, String) — This tag is embedded under the <Package> tag. Enter the number of packages for the accompanying <ServiceType> tag. Maximum characters allowed: 3 or 999 packages. If your pickup contains more than one Service Type, use additional <Package> tags for each service type with the accompanying <ServiceType> and <Count> tags. Refer to the XML request example section, below, to see how these embedded tags are formatted. For example: <Count>2</Count>
  * *:estimated_weight* (required, String) — Enter the estimated aggregate weight (in pounds) of all packages being picked up. For example: <EstimatedWeight>14</EstimatedWeight>
  * *:package_location* (required, String) — Enter one of the following values: Note: "Other" requires information in the value for the <SpecialInstructions> tag. For example: <PackageLocation>Front Door</PackageLocation>
  * *:special_instructions* (String) — Value Required when PackageLocation is “Other”. Only alpha, numeric, commas, periods, apostrophes, _, &, -, ( ), ?, #, / +, @ and space characters may be used. For example: <SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>
  * *:email_address* (String) — If provided, email notifications will be sent confirming package pickup, or request changes and cancellations. Maximum characters allowed: 50. For example: <EmailAddress>cpapple@email.com</EmailAddress>
# File lib/usps/api/endpoints/carrier_pickup_schedule.rb, line 34
def carrier_pickup_schedule(options = {})
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request missing') if options[:carrier_pickup_schedule_request].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :first_name missing') if options[:carrier_pickup_schedule_request][:first_name].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :last_name missing') if options[:carrier_pickup_schedule_request][:last_name].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :suite_or_apt missing') if options[:carrier_pickup_schedule_request][:suite_or_apt].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :address2 missing') if options[:carrier_pickup_schedule_request][:address2].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :urbanization missing') if options[:carrier_pickup_schedule_request][:urbanization].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :city missing') if options[:carrier_pickup_schedule_request][:city].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :state missing') if options[:carrier_pickup_schedule_request][:state].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :zip5 missing') if options[:carrier_pickup_schedule_request][:zip5].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :zip4 missing') if options[:carrier_pickup_schedule_request][:zip4].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :phone missing') if options[:carrier_pickup_schedule_request][:phone].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :package missing') if options[:carrier_pickup_schedule_request][:package].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :package, :service_type missing') if options[:carrier_pickup_schedule_request][:package][:service_type].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :package, :count missing') if options[:carrier_pickup_schedule_request][:package][:count].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :package, :estimated_weight missing') if options[:carrier_pickup_schedule_request][:package][:estimated_weight].nil?
                                        throw ArgumentError.new('Required arguments :carrier_pickup_schedule_request, :package, :package_location missing') if options[:carrier_pickup_schedule_request][:package][:package_location].nil?

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

Private Instance Methods

build_carrier_pickup_schedule_request(xml, options = {}) click to toggle source
# File lib/usps/api/endpoints/carrier_pickup_schedule.rb, line 65
def build_carrier_pickup_schedule_request(xml, options = {})
        xml.tag!('FirstName', options[:carrier_pickup_schedule_request][:first_name])
        xml.tag!('LastName', options[:carrier_pickup_schedule_request][:last_name])
        tag_unless_blank(xml, 'FirmName', options[:carrier_pickup_schedule_request][:firm_name])
        xml.tag!('SuiteOrApt', options[:carrier_pickup_schedule_request][:suite_or_apt])
        xml.tag!('Address2', options[:carrier_pickup_schedule_request][:address2])
        xml.tag!('Urbanization', options[:carrier_pickup_schedule_request][:urbanization])
        xml.tag!('City', options[:carrier_pickup_schedule_request][:city])
        xml.tag!('State', options[:carrier_pickup_schedule_request][:state])
        xml.tag!('ZIP5', options[:carrier_pickup_schedule_request][:zip5])
        xml.tag!('ZIP4', options[:carrier_pickup_schedule_request][:zip4])
        xml.tag!('Phone', options[:carrier_pickup_schedule_request][:phone])
        tag_unless_blank(xml, 'Extension', options[:carrier_pickup_schedule_request][:extension])
        xml.tag!('Package') do
                xml.tag!('ServiceType', options[:carrier_pickup_schedule_request][:package][:service_type])
                xml.tag!('Count', options[:carrier_pickup_schedule_request][:package][:count])
                xml.tag!('EstimatedWeight', options[:carrier_pickup_schedule_request][:package][:estimated_weight])
                xml.tag!('PackageLocation', options[:carrier_pickup_schedule_request][:package][:package_location])
                tag_unless_blank(xml, 'SpecialInstructions', options[:carrier_pickup_schedule_request][:package][:special_instructions])
                tag_unless_blank(xml, 'EmailAddress', options[:carrier_pickup_schedule_request][:package][:email_address])
        end 
        xml.target!
end
tag_unless_blank(xml, tag_name, data) click to toggle source
# File lib/usps/api/endpoints/carrier_pickup_schedule.rb, line 61
def tag_unless_blank(xml, tag_name, data)
        xml.tag!(tag_name, data) unless data.blank? || data.nil?
end