shippex v0.2.0 Shippex

Configuration

config :shippex,
  env: :dev,
  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"
      }
    ]
  ]

Create origin/destination addresses

origin = Shippex.Address.to_struct(%{
  name: "Earl G",
  phone: "123-123-1234",
  address: "9999 Hobby Lane",
  address_line_2: nil,
  city: "Austin",
  state: "TX",
  zip: "78703"
})

destination = Shippex.Address.to_struct(%{
  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))

Summary

Functions

cancel_shipment(label)

Cancels the shipment associated with label, if possible. The result is returned in a tuple

carriers()

Provides a method of returning all available carriers. This is based on the config and does not include validation

env()

Fetches the env atom for the config. Must be either :dev or :prod, or an exception will be thrown

fetch_label(shipment, service)

Fetches the label for shipment for a specific Service. The service module contains the Carrier and selected delivery speed

fetch_rate(shipment, service)

Fetches the rate for shipment for a specific Service. The service module contains the Carrier and selected delivery speed

fetch_rates(shipment, carriers \\ :all)

Fetches rates from carriers for a given Shipment

validate_address(address)

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

Types

response()

response() :: %{code: String.t, message: String.t}

Functions

cancel_shipment(label)

cancel_shipment(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.

case Shippex.cancel_shipment(label) do
  {:ok, result} ->
    IO.inspect(result) #=> %{code: "1", message: "Voided successfully."}
  {:error, %{code: code, message: message}} ->
    IO.inspect(code)
    IO.inspect(message)
end

carriers()

carriers() :: [atom]

Provides a method of returning all available carriers. This is based on the config and does not include validation.

Shippex.carriers #=> [:ups]

env()

env() :: atom

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, service)

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, 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, carriers \\ :all)

fetch_rates(Shipment.t, [atom]) :: [{atom, Rate.t}]

Fetches rates from carriers for a given Shipment.

validate_address(address)

validate_address(Address.t) :: {atom, response | [Address.t]}

Note that the candidates returned will automatically pass through Shippex.Address.to_struct() for casting.

address = Shippex.Address.to_struct(%{
  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} ->
    if length(candidates) == 1 do
      # Use the address
    else
      # Present candidates to user for selection
    end
end