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

class_name, #delete, each, get_next_page_exec, #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

.all(filters = {}, api_key = nil) ⇒ Object

Retrieve a list of Shipment objects.



38
39
40
41
42
43
44
45
 
# File 'lib/easypost/shipment.rb', line 38

def self.all(filters = {}, api_key = nil)
  collection = super(filters, api_key)

  # Store the filters used to retrieve the collection.
  collection.refresh_from({ include_children: filters[:include_children], purchased: filters[:purchased] }, api_key)

  collection
end

.build_next_page_params(collection, current_page_items, page_size = nil) ⇒ Object

Build the next page parameters.



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

def self.build_next_page_params(collection, current_page_items, page_size = nil)
  params = {}
  params[:before_id] = current_page_items.last.id
  unless page_size.nil?
    params[:page_size] = page_size
  end
  unless collection.include_children.nil?
    params[:include_children] = collection.include_children
  end
  unless collection.purchased.nil?
    params[:purchased] = collection.purchased
  end
  params
end

.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.



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/easypost/shipment.rb', line 141

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

.get_next_page(collection, page_size = nil) ⇒ Object

Get the next page of shipments.



48
49
50
 
# File 'lib/easypost/shipment.rb', line 48

def self.get_next_page(collection, page_size = nil)
  get_next_page_exec(method(:all), collection, collection.shipments, page_size)
end

Instance Method Details

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

Buy a Shipment.



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/easypost/shipment.rb', line 69

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

  if params[:with_carbon_offset]
    params[:carbon_offset] = params[:with_carbon_offset]
    params.delete(:with_carbon_offset)
  else
    params[:carbon_offset] = with_carbon_offset
  end

  if end_shipper_id
    params[:end_shipper_id] = end_shipper_id
  end

  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.



173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/easypost/shipment.rb', line 173

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.



94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/easypost/shipment.rb', line 94

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.



116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/easypost/shipment.rb', line 116

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).



130
131
132
 
# File 'lib/easypost/shipment.rb', line 130

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.



135
136
137
138
 
# File 'lib/easypost/shipment.rb', line 135

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.



108
109
110
111
112
113
 
# File 'lib/easypost/shipment.rb', line 108

def refund(params = {})
  response = EasyPost.make_request(:post, "#{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