shippex v0.4.4 Shippex
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",
include_library_mail: true
include_media_mail: true
]
]
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"
}
Link the origin, destination, and package with a Shipment
shipment = %Shippex.Shipment{
from: origin,
to: destination,
package: package
}
Fetch rates to present to the user.
rates = Shippex.fetch_rates(shipment)
Accept one of the services and print the label
{:ok, rate} = Enum.shuffle(rates) |> hd
{:ok, label} = Shippex.fetch_label(rate, shipment)
Write the label gif to disk
File.write!("#{label.tracking_number}.gif", Base.decode64!(label.image))
Link to this section Summary
Functions
Cancels the shipment associated with label
, if possible. The result is
returned in a tuple
Provides a method of returning all available carriers. This is based on the config and does not include validation
Returns the configured currency code. Raises an error if an invalid code was used
Fetches the env atom for the config. Must be either :dev
or :prod
, or an
exception will be thrown
Fetches the label for shipment
for a specific Service
. The service
module contains the Carrier
and selected delivery speed
Fetches the rate for shipment
for a specific Service
. The service
module
contains the Carrier
and selected delivery speed
Fetches rates from carriers
for a given Shipment
Performs address validation. If the address is completely invalid,
{:error, result}
is returned. For addresses that may have typos,
{:ok, candidates}
is returned. You can iterate through the list of
candidates to present to the end user. Addresses that pass validation
perfectly will still be in a list
where length(candidates) == 1
Link to this section Types
Link to this section Functions
cancel_shipment(Shippex.Carrier.t, Label.t | String.t) :: {atom, response}
Cancels the shipment associated with label
, if possible. The result is
returned in a tuple.
You may pass in either the label or tracking number. A carrier must be specified.
case Shippex.cancel_shipment(:ups, label) do
{:ok, result} ->
IO.inspect(result) #=> %{code: "1", message: "Voided successfully."}
{:error, %{code: code, message: message}} ->
IO.inspect(code)
IO.inspect(message)
end
Provides a method of returning all available carriers. This is based on the config and does not include validation.
Shippex.carriers #=> [:ups]
Returns the configured currency code. Raises an error if an invalid code was used.
config :shippex, :currency, :can
Shippex.currency_code() #=> "CAN"
Fetches the env atom for the config. Must be either :dev
or :prod
, or an
exception will be thrown.
config :shippex, :env, :dev
Shippex.env #=> :dev
fetch_label(Shipment.t, Service.t) :: {atom, Label.t}
Fetches the label for shipment
for a specific Service
. The service
module contains the Carrier
and selected delivery speed.
Shippex.fetch_label(shipment, service)
fetch_rate(Shipment.t, Service.t) :: {atom, Rate.t}
Fetches the rate for shipment
for a specific Service
. The service
module
contains the Carrier
and selected delivery speed.
Shippex.fetch_rate(shipment, service)
fetch_rates(Shipment.t, [Shippex.Carrier.t] | nil) :: [{atom, Rate.t}]
Fetches rates from carriers
for a given Shipment
.
validate_address(Shippex.Carrier.t, Address.t) :: {atom, response | [Address.t]}
Performs address validation. If the address is completely invalid,
{:error, result}
is returned. For addresses that may have typos,
{:ok, candidates}
is returned. You can iterate through the list of
candidates to present to the end user. Addresses that pass validation
perfectly will still be in a list
where length(candidates) == 1
.
Note that the candidates
returned will automatically pass through
Shippex.Address.address()
for casting. Also, if :usps
is used as the
validation provider, the number of candidates will always be 1.
address = Shippex.Address.address(%{
name: "Earl G",
phone: "123-123-1234",
address: "9999 Hobby Lane",
address_line_2: nil,
city: "Austin",
state: "TX",
zip: "78703"
})
case Shippex.validate_address(address) do
{:error, %{code: code, message: message}} ->
# Present the error.
{:ok, candidates} when length(candidates) == 1 ->
# Use the address
{:ok, candidates} when length(candidates) > 1 ->
# Present candidates to user for selection
end