Class: EasyPost::Shipment

Inherits:
Resource show all
Defined in:
lib/easypost/shipment.rb

Overview

The workhorse of the EasyPost API, a Shipment is made up of a “to” and “from” Address, the Parcel being shipped, and any customs forms required for international deliveries.

Instance Attribute Summary

Attributes inherited from EasyPostObject

#api_key, #name, #parent, #unsaved_values

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Resource

all, class_name, #delete, each, #refresh, retrieve, #save, url, #url

Methods inherited from EasyPostObject

#[], #[]=, #as_json, construct_from, #deconstruct_keys, #each, #id, #id=, #initialize, #inspect, #keys, #refresh_from, #to_hash, #to_json, #to_s, #values

Constructor Details

This class inherits a constructor from EasyPost::EasyPostObject

Class Method Details

.create(params = {}, api_key = nil, with_carbon_offset = false) ⇒ Object

Create a Shipment.



9
10
11
12
13
14
15
16
17
 
# File 'lib/easypost/shipment.rb', line 9

def self.create(params = {}, api_key = nil, with_carbon_offset = false)
  wrapped_params = {
    shipment: params,
    carbon_offset: with_carbon_offset,
  }

  response = EasyPost.make_request(:post, url, api_key, wrapped_params)
  EasyPost::Util.convert_to_easypost_object(response, api_key)
end

.get_lowest_smartrate(smartrates, delivery_days, delivery_accuracy) ⇒ Object

Get the lowest smartrate from a list of smartrates.



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/easypost/shipment.rb', line 101

def self.get_lowest_smartrate(smartrates, delivery_days, delivery_accuracy)
  valid_delivery_accuracy_values = Set[
    'percentile_50',
    'percentile_75',
    'percentile_85',
    'percentile_90',
    'percentile_95',
    'percentile_97',
    'percentile_99',
  ]
  lowest_smartrate = nil

  unless valid_delivery_accuracy_values.include?(delivery_accuracy.downcase)
    raise EasyPost::Error.new("Invalid delivery accuracy value, must be one of: #{valid_delivery_accuracy_values}")
  end

  smartrates.each do |rate|
    next if rate['time_in_transit'][delivery_accuracy] > delivery_days.to_i

    if lowest_smartrate.nil? || rate['rate'].to_f < lowest_smartrate['rate'].to_f
      lowest_smartrate = rate
    end
  end

  if lowest_smartrate.nil?
    raise EasyPost::Error.new('No rates found.')
  end

  lowest_smartrate
end

Instance Method Details

#buy(params = {}, with_carbon_offset = false) ⇒ Object

Buy a Shipment.



38
39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/easypost/shipment.rb', line 38

def buy(params = {}, with_carbon_offset = false)
  if params.instance_of?(EasyPost::Rate)
    temp = params.clone
    params = {}
    params[:rate] = temp
  end

  params[:carbon_offset] = with_carbon_offset

  response = EasyPost.make_request(:post, "#{url}/buy", @api_key, params)
  refresh_from(response, @api_key)

  self
end

#generate_form(form_type, form_options = {}) ⇒ Object

Generate a form for a Shipment.



133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/easypost/shipment.rb', line 133

def generate_form(form_type, form_options = {})
  params = {}
  params[:type] = form_type
  merged_params = params.merge(form_options)
  wrapped_params = {
    form: merged_params,
  }

  response = EasyPost.make_request(:post, "#{url}/forms", @api_key, wrapped_params)
  refresh_from(response, @api_key)

  self
end

#get_smartrates ⇒ Object

Get the SmartRates of a Shipment.



31
32
33
34
35
 
# File 'lib/easypost/shipment.rb', line 31

def get_smartrates # rubocop:disable Naming/AccessorMethodName
  response = EasyPost.make_request(:get, "#{url}/smartrate", @api_key)

  response.fetch('result', [])
end

#insure(params = {}) ⇒ Object

Insure a Shipment.



54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/easypost/shipment.rb', line 54

def insure(params = {})
  if params.is_a?(Integer) || params.is_a?(Float)
    temp = params.clone
    params = {}
    params[:amount] = temp
  end

  response = EasyPost.make_request(:post, "#{url}/insure", @api_key, params)
  refresh_from(response, @api_key)

  self
end

#label(params = {}) ⇒ Object

Convert the label format of a Shipment.



76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/easypost/shipment.rb', line 76

def label(params = {})
  if params.is_a?(String)
    temp = params.clone
    params = {}
    params[:file_format] = temp
  end

  response = EasyPost.make_request(:get, "#{url}/label", @api_key, params)
  refresh_from(response, @api_key)

  self
end

#lowest_rate(carriers = [], services = []) ⇒ Object

Get the lowest rate of a Shipment (can exclude by having `'!'` as the first element of your optional filter lists).



90
91
92
 
# File 'lib/easypost/shipment.rb', line 90

def lowest_rate(carriers = [], services = [])
  EasyPost::Util.get_lowest_object_rate(self, carriers, services)
end

#lowest_smartrate(delivery_days, delivery_accuracy) ⇒ Object

Get the lowest smartrate of a Shipment.



95
96
97
98
 
# File 'lib/easypost/shipment.rb', line 95

def lowest_smartrate(delivery_days, delivery_accuracy)
  smartrates = get_smartrates
  EasyPost::Shipment.get_lowest_smartrate(smartrates, delivery_days, delivery_accuracy)
end

#refund(params = {}) ⇒ Object

Refund a Shipment.



68
69
70
71
72
73
 
# File 'lib/easypost/shipment.rb', line 68

def refund(params = {})
  response = EasyPost.make_request(:get, "#{url}/refund", @api_key, params)
  refresh_from(response, @api_key)

  self
end

#regenerate_rates(with_carbon_offset = false) ⇒ Object

Regenerate the rates of a Shipment.



20
21
22
23
24
25
26
27
28
 
# File 'lib/easypost/shipment.rb', line 20

def regenerate_rates(with_carbon_offset = false)
  params = {}
  params[:carbon_offset] = with_carbon_offset

  response = EasyPost.make_request(:post, "#{url}/rerate", @api_key, params)
  refresh_from(response, @api_key)

  self
end