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.



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/easypost/shipment.rb', line 110

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, end_shipper_id = nil) ⇒ Object

Buy a Shipment.



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/easypost/shipment.rb', line 38

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.



142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/easypost/shipment.rb', line 142

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.



63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/easypost/shipment.rb', line 63

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.



85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/easypost/shipment.rb', line 85

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



99
100
101
 
# File 'lib/easypost/shipment.rb', line 99

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.



104
105
106
107
 
# File 'lib/easypost/shipment.rb', line 104

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.



77
78
79
80
81
82
 
# File 'lib/easypost/shipment.rb', line 77

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