Class: FriendlyShipping::Services::ShipEngine

Inherits:
Object
  • Object
show all
Defined in:
lib/friendly_shipping/services/ship_engine.rb,
lib/friendly_shipping/services/ship_engine/api_error.rb,
lib/friendly_shipping/services/ship_engine/label_options.rb,
lib/friendly_shipping/services/ship_engine/rates_options.rb,
lib/friendly_shipping/services/ship_engine/label_item_options.rb,
lib/friendly_shipping/services/ship_engine/rates_item_options.rb,
lib/friendly_shipping/services/ship_engine/parse_void_response.rb,
lib/friendly_shipping/services/ship_engine/parse_label_response.rb,
lib/friendly_shipping/services/ship_engine/parse_rates_response.rb,
lib/friendly_shipping/services/ship_engine/label_customs_options.rb,
lib/friendly_shipping/services/ship_engine/label_package_options.rb,
lib/friendly_shipping/services/ship_engine/rates_package_options.rb,
lib/friendly_shipping/services/ship_engine/parse_carrier_response.rb,
lib/friendly_shipping/services/ship_engine/rate_estimates_options.rb,
lib/friendly_shipping/services/ship_engine/serialize_rates_request.rb,
lib/friendly_shipping/services/ship_engine/customs_items_serializer.rb,
lib/friendly_shipping/services/ship_engine/serialize_label_shipment.rb,
lib/friendly_shipping/services/ship_engine/parse_rate_estimates_response.rb,
lib/friendly_shipping/services/ship_engine/serialize_rate_estimate_request.rb,
lib/friendly_shipping/services/ship_engine/parse_address_validation_response.rb,
lib/friendly_shipping/services/ship_engine/serialize_address_validation_request.rb,
lib/friendly_shipping/services/ship_engine/serialize_address_residential_indicator.rb

Overview

API service class for ShipEngine, a shipping API supporting UPS, USPS, etc.

See Also:

Defined Under Namespace

Classes: ApiError, CustomsItemsSerializer, LabelCustomsOptions, LabelItemOptions, LabelOptions, LabelPackageOptions, ParseAddressValidationResponse, ParseCarrierResponse, ParseLabelResponse, ParseRateEstimatesResponse, ParseRatesResponse, ParseVoidResponse, RateEstimatesOptions, RatesItemOptions, RatesOptions, RatesPackageOptions, SerializeAddressResidentialIndicator, SerializeAddressValidationRequest, SerializeLabelShipment, SerializeRateEstimateRequest, SerializeRatesRequest

Constant Summary collapse

API_BASE =

The API base URL.

"https://api.shipengine.com/v1/"
API_PATHS =

The API paths. Used when constructing endpoint URLs.

{
  carriers: "carriers",
  labels: "labels"
}.freeze

Instance Method Summary collapse

Constructor Details

#initialize(token:, test: true, client: nil) ⇒ ShipEngine

Returns a new instance of ShipEngine.

Parameters:

  • token (String) —

    the API token

  • test (Boolean) (defaults to: true) —

    whether to use test API endpoints

  • client (HttpClient) (defaults to: nil) —

    optional custom HTTP client to use for requests



22
23
24
25
26
27
28
 
# File 'lib/friendly_shipping/services/ship_engine.rb', line 22

def initialize(token:, test: true, client: nil)
  @token = token
  @test = test

  error_handler = ApiErrorHandler.new(api_error_class: ShipEngine::ApiError)
  @client = client || HttpClient.new(error_handler: error_handler)
end

Instance Method Details

#carriers(debug: false) ⇒ ApiResult<Array<Carrier>>, Failure<ApiResult>

Get configured carriers.

Parameters:

  • debug (Boolean) (defaults to: false) —

    whether to attach debugging information to the response

Returns:



34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/friendly_shipping/services/ship_engine.rb', line 34

def carriers(debug: false)
  request = FriendlyShipping::Request.new(
    url: API_BASE + API_PATHS[:carriers],
    http_method: "GET",
    headers: request_headers,
    debug: debug
  )
  client.get(request).fmap do |response|
    ParseCarrierResponse.call(request: request, response: response)
  end
end

#labels(shipment, options:, debug: false) ⇒ ApiResult<Array<Label>>, Failure<ApiResult>

Get shipping labels.

Parameters:

  • shipment (Physical::Shipment) —

    The shipment for which we're getting labels. Note: Some ShipEngine carriers, notably USPS, only support one package per shipment, and that's all that the integration supports at this point.

  • options (LabelOptions) —

    the options for getting labels (see object description)

  • debug (Boolean) (defaults to: false) —

    whether to attach debugging information to the response

Returns:



99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/friendly_shipping/services/ship_engine.rb', line 99

def labels(shipment, options:, debug: false)
  request = FriendlyShipping::Request.new(
    url: API_BASE + API_PATHS[:labels],
    http_method: "POST",
    body: SerializeLabelShipment.call(shipment: shipment, options: options, test: test).to_json,
    headers: request_headers,
    debug: debug
  )
  client.post(request).fmap do |response|
    ParseLabelResponse.call(request: request, response: response)
  end
end

#rate_estimates(shipment, options: FriendlyShipping::Services::ShipEngine::RateEstimatesOptions.new, debug: false) ⇒ Success<ApiResult<Array<Rate>>>, Failure<ApiResult<Array<String>>> Also known as: timings

Get rate estimates.

Parameters:

  • shipment (Physical::Shipment) —

    the shipment for which we're getting rate estimates

  • options (RateEstimatesOptions) (defaults to: FriendlyShipping::Services::ShipEngine::RateEstimatesOptions.new) —

    the options for getting rate estimates (see object description)

Returns:

  • (Success<ApiResult<Array<Rate>>>, Failure<ApiResult<Array<String>>>) —

    When successfully parsing, an array of rates in a Success Monad. When the parsing is not successful or ShipEngine can't give us rates, a Failure monad containing something that can be serialized into an error message using to_s.



75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/friendly_shipping/services/ship_engine.rb', line 75

def rate_estimates(shipment, options: FriendlyShipping::Services::ShipEngine::RateEstimatesOptions.new, debug: false)
  request = FriendlyShipping::Request.new(
    url: "#{API_BASE}rates/estimate",
    http_method: "POST",
    body: SerializeRateEstimateRequest.call(shipment: shipment, options: options).to_json,
    headers: request_headers,
    debug: debug
  )
  client.post(request).bind do |response|
    ParseRateEstimatesResponse.call(response: response, request: request, options: options)
  end
end

#rates(shipment, options:, debug: false) ⇒ Success<ApiResult<Array<Rate>>>, ...

Get rates.

Parameters:

  • shipment (Physical::Shipment) —

    the shipment for which we're getting rates

  • options (RatesOptions) —

    the options for getting rates (see object description)

Returns:

  • (Success<ApiResult<Array<Rate>>>, Failure<ApiResult<Array<String>>] When successfully parsing, an array of rates in a Success Monad. When the parsing is not successful or ShipEngine can't give us rates, a Failure monad containing something that can be serialized into an error message using `to_s`.) —

    Success>>, Failure>] When successfully parsing, an array of rates in a Success Monad. When the parsing is not successful or ShipEngine can't give us rates, a Failure monad containing something that can be serialized into an error message using to_s.



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

def rates(shipment, options:, debug: false)
  request = FriendlyShipping::Request.new(
    url: "#{FriendlyShipping::Services::ShipEngine::API_BASE}rates",
    http_method: "POST",
    body: SerializeRatesRequest.call(shipment: shipment, options: options).to_json,
    headers: request_headers,
    debug: debug
  )
  client.post(request).bind do |response|
    ParseRatesResponse.call(response: response, request: request, options: options)
  end
end

#validate_address(location, debug: false) ⇒ Success<ApiResult<Array<Physical::Location>>>, Failure<ApiResult> Also known as: city_state_lookup

Validate an address using ShipEngine

Parameters:

  • location (Physical::Location) —

    the address to validate

Returns:



134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/friendly_shipping/services/ship_engine.rb', line 134

def validate_address(location, debug: false)
  request = FriendlyShipping::Request.new(
    url: "#{API_BASE}addresses/validate",
    http_method: "POST",
    body: SerializeAddressValidationRequest.call(location: location).to_json,
    headers: request_headers,
    debug: debug
  )
  client.post(request).bind do |response|
    ParseAddressValidationResponse.call(response: response, request: request)
  end
end

#void(label, debug: false) ⇒ Success<ApiResult<String>>, Failure<ApiResult<String>>

Void a shipping label.

Parameters:

  • label (Label) —

    the label to void

  • debug (Boolean) (defaults to: false) —

    whether to include debugging information in the result

Returns:

  • (Success<ApiResult<String>>, Failure<ApiResult<String>>) —

    the success or failure message



117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/friendly_shipping/services/ship_engine.rb', line 117

def void(label, debug: false)
  request = FriendlyShipping::Request.new(
    url: "#{API_BASE}labels/#{label.id}/void",
    http_method: "PUT",
    body: '',
    headers: request_headers,
    debug: debug
  )
  client.put(request).bind do |response|
    ParseVoidResponse.call(request: request, response: response)
  end
end