shippex v0.6.8 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
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.Transaction.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)
fetch_rate(Shippex.Shipment.t, atom | Shippex.Service.t) :: {atom, Shippex.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, Shippex.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.
validate_address(Shippex.Address.t, Keyword.t) :: {atom, response | [Shippex.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