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)
