shippex v0.6.3 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"
]
]
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 transaction 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
Fetches the label for shipment
for a specific Service
. The service
module contains the Carrier
and selected delivery speed
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 rate for shipment
for a specific Service
. The service
module
contains the Carrier
and selected delivery speed. You can also pass in the
ID of the service
Fetches rates for a given shipment
. Possible options
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_transaction(Shippex.Transaction.t) :: {atom, response}
Cancels the transaction associated with label
, if possible. The result is
returned in a tuple.
You may pass in either the transaction, or if the full transaction struct isn’t available, you may pass in the carrier, shipment, and tracking number instead.
case Shippex.cancel_shipment(transaction) do
{:ok, result} ->
IO.inspect(result) #=> %{code: "1", message: "Voided successfully."}
{:error, %{code: code, message: message}} ->
IO.inspect(code)
IO.inspect(message)
end
cancel_transaction(Shippex.Carrier.t, Shippex.Shipment.t, String.t) :: {atom, response}
Provides a method of returning all available carriers. This is based on the config and does not include validation.
Shippex.carriers #=> [:ups]
create_transaction(Shippex.Shipment.t, Shippex.Service.t) :: {atom, Shippex.Label.t}
Fetches the label for shipment
for a specific Service
. The service
module contains the Carrier
and selected delivery speed.
Shippex.create_transaction(shipment, service)
Returns the configured currency code. Raises an error if an invalid code was used.
iex> Application.put_env(:shippex, :currency, :mxn)
iex> Shippex.currency_code
"MXN"
iex> Application.put_env(:shippex, :currency, :can)
iex> Shippex.currency_code
"CAN"
iex> Application.put_env(:shippex, :currency, :usd)
iex> Shippex.currency_code
"USD"
Fetches the env atom for the config. Must be either :dev
or :prod
, or an
exception will be thrown.
iex> Application.put_env(:shippex, :env, :dev)
iex> Shippex.env
:dev
fetch_rate(Shippex.Shipment.t, atom | Shippex.Service.t) :: {atom, Rate.t}
Fetches the rate for shipment
for a specific Service
. The service
module
contains the Carrier
and selected delivery speed. You can also pass in the
ID of the service.
Shippex.fetch_rate(shipment, service)
fetch_rates(Shippex.Shipment.t, Keyword.t) :: [{atom, Rate.t}]
Fetches rates for a given shipment
. Possible options:
carriers
- Fetches rates for all services for the given carriersservices
- Fetches rates only for the given services
These may be used in combination. To fetch rates for all UPS services, as well as USPS Priority, for example:
Shippex.fetch_rates(shipment, carriers: :ups, services: [:usps_priority])
If no options are provided, Shippex will fetch rates for every service from every available carrier.
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