shippex v0.4.0 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"
}
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 type response()
response() :: %{code: String.t, message: String.t}

Link to this section Functions

Link to this function cancel_shipment(carrier, label_or_tracking_number)
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
Link to this function carriers()
carriers() :: [Shippex.Carrier.t]

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

Shippex.carriers #=> [:ups]
Link to this function currency_code()
currency_code() :: String.t

Returns the configured currency code. Raises an error if an invalid code was used.

config :shippex, :currency, :can

Shippex.currency_code() #=> "CAN"
Link to this function 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
Link to this function 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)
Link to this function 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)
Link to this function fetch_rates(shipment, carriers \\ nil)
fetch_rates(Shipment.t, [Shippex.Carrier.t] | nil) :: [{atom, Rate.t}]

Fetches rates from carriers for a given Shipment.

Link to this function validate_address(carrier \\ :usps, address)
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