How to Use Shippo API to Manage Shipping in Ruby

Initialize the Shippo Client

• First, you'll need to initialize the Shippo client using the API key you received. This establishes the connection and allows you to make requests to the Shippo API.

require 'shippo'

# Initialize the Shippo client
Shippo::api_token = '<YOUR_API_KEY>'

Create Shipments

• Creating a shipment involves specifying the details of the sender, recipient, and package. These entities have specific attributes that need to be set according to the API documentation.

from_address = {
  :name => 'Shawn Ippotle',
  :street1 => '215 Clayton St.',
  :city => 'San Francisco',
  :state => 'CA',
  :zip => '94117',
  :country => 'US',
}

to_address = {
  :name => 'Mr. Hippo',
  :street1 => '965 Mission St.',
  :city => 'San Francisco',
  :state => 'CA',
  :zip => '94103',
  :country => 'US',
}

parcel = {
  :length => '10',
  :width => '15',
  :height => '20',
  :distance_unit => 'cm',
  :weight => '5',
  :mass_unit => 'kg'
}

shipment = Shippo::Shipment.create(
  :address_from => from_address,
  :address_to => to_address,
  :parcels => parcel,
  :async => false
)

Get Shipping Rates

• Once a shipment is created, you can retrieve available shipping rates for it. This allows you to choose the most suitable shipping option based on price and delivery time.

rates = shipment[:rates_list]
rates.each do |rate|
  puts "Carrier: #{rate[:provider]} Price: #{rate[:amount]} #{rate[:currency]} Estimated Days: #{rate[:estimated_days]}"
end

Select and Purchase a Rate

• After reviewing the rates, select one that meets your needs and purchase the shipment label.

selected_rate = rates.first

transaction = Shippo::Transaction.create(
  :rate => selected_rate[:object_id],
  :async => false
)

if transaction[:status] == 'SUCCESS'
  puts "Label URL: #{transaction[:label_url]}"
else
  puts "Transaction failed: #{transaction[:messages]}"
end

Track Shipments

• Track your shipments using tracking numbers. Shippo provides convenient endpoints to retrieve up-to-date tracking information.

tracking_info = Shippo::Track.get(carrier: 'usps', tracking_number: 'TRACKING_NUMBER')
puts tracking_info[:tracking_status][:status_details]

Webhook Integration for Real-time Updates

• Shippo allows setting up webhooks to receive real-time updates about events such as shipment status changes. This is useful for automated systems needing immediate processing.

# Example for setting a webhook in Rails
class ShipmentsController < ApplicationController
  protect_from_forgery except: :webhook

  def webhook
    header_signature = request.headers['HTTP_SHIPPO_SIGNATURE']

    # Verify the signature here
    render json: { message: 'Invalid signature' }, status: :forbidden and return unless valid_signature?(header_signature)

    # Process the webhook event
    shipment_event = JSON.parse(request.body.read)

    # Your logic to handle the event
  end

  private

  def valid_signature?(header_signature)
    # Implement your signature verification logic
  end
end

Optimize and Automate

• Integrate the Shippo API operations within larger processes in your Ruby application. This can involve automatic order fulfillment, analytics for shipment costs, or building a user interface for logistics management.
• Utilize background jobs for async tasks to manage API calls efficiently, ensuring a responsive application even when performing complex operations.

# Example using Sidekiq
class ShippingLabelJob
  include Sidekiq::Worker

  def perform(order_id)
    order = Order.find(order_id)
    
    # Your shipment creation logic here
  end
end

ShippingLabelJob.perform_async(order.id)