shippex v0.8.0 API Reference
Modules
Configuration
config :shippex,
env: :dev,
distance_unit: :in, # either :in or :cm
weight_unit: :lbs, # either :lbs or :kg
currency: :usd, # :usd, :can, :mxn, :eur
carriers: [
ups: [
username: "MyUsername",
password: "MyPassword",
secret_key: "123123",
shipper: %{
account_number: "AB1234",
name: "My Company",
phone: "123-456-7890",
address: "1234 Foo St",
city: "Foo",
state: "TX",
zip: "78999"
}
],
usps: [
username: "MyUsername",
password: "MyPassword"
]
]
Create origin/destination addresses
origin = Shippex.Address.address(%{
name: "Earl G",
phone: "123-123-1234",
address: "9999 Hobby Lane",
address_line_2: nil,
city: "Austin",
state: "TX",
zip: "78703"
})
destination = Shippex.Address.address(%{
name: "Bar Baz",
phone: "123-123-1234",
address: "1234 Foo Blvd",
address_line_2: nil,
city: "Plano",
state: "TX",
zip: "75074"
})
Create a package
# Currently only inches and pounds (lbs) supported.
package = %Shippex.Package{
length: 8,
width: 8,
height: 4,
weight: 5,
description: "Headphones",
monetary_value: 20 # optional
}
Link the origin, destination, and package with a Shipment
shipment = Shippex.Shipment.shipment(origin, destination, package)
Fetch rates to present to the user.
rates = Shippex.fetch_rates(shipment, carriers: [:usps, :ups])
Accept one of the services and print the label
{:ok, rate} = Enum.shuffle(rates) |> hd
{:ok, transaction} = Shippex.create_transaction(shipment, rate.service)
label = transaction.label
Write the label gif to disk
File.write!("#{label.tracking_number}.gif", Base.decode64!(label.image))
Represents an address that can be passed to other Shippex
functions. Do
not initialize this struct directly. Instead, use address/1
.
Defines a behaviour for implementing a new Carrier module. Includes a helper function for fetching the Carrier module.
This module contains data and functions for obtaining geographic data in compliance with the ISO-3166-2 standard.
Defines a struct for storing an Item
in a Package
.
Defines the struct for storing a returned Rate
, along with the tracking
number, base64-encoded image and its format.
Defines the struct for storing a Package
, which is then passed along with
an origin and destination address for shipping estimates. A description
is
optional, as it may or may not be used with various carriers.
A Rate
is a representation of a price estimate from a given carrier for a
Service
, which is typically selected by the end user for a desired shipping
speed.
A Service
represents a carrier's offered shipping option. This is not
initialized by the user directly. However, some convenience functions exist
to display all offered carrier services to the user.
A Shipment
represents everything needed to fetch rates from carriers: an
origin, a destination, and a package description. An optional :id
field
is provided in the struct, which may be used by the end user to represent the
user's internal identifier for the shipment. The id is not used by Shippex.