View Source ExPorterSDK (ExPorterSDK v0.1.0)
An Elixir SDK for Porter's delivery API, providing a simple and reliable way to integrate Porter's logistics services into your Elixir applications.
Features
- Get delivery quotes based on locations
- Create and manage delivery orders
- Track order status in real-time
- Cancel existing orders
- Comprehensive test helpers and stubs
Installation
Add ex_porter_sdk
to your list of dependencies in mix.exs
:
def deps do
[
{:ex_porter_sdk, "~> 0.1.0"}
]
end
Configuration
Configure the SDK in your config.exs
or appropriate environment config file:
config :ex_porter_sdk,
base_url: System.get_env("PORTER_BASE_URL", "https://api.porter.in"),
api_key: System.get_env("PORTER_API_KEY"),
quote_impl: ExPorterSDK.Quote.Impl, # Optional, defaults to Impl
order_impl: ExPorterSDK.Order.Impl # Optional, defaults to Impl
Basic Usage
Get Delivery Quote
params = %{
pickup_details: %{lat: 12.909728534457143, lng: 77.6001397394293},
drop_details: %{lat: 12.89795704454522, lng: 77.62119799020186},
customer: %{
name: "Test User",
mobile: %{number: "7678139714", country_code: "+91"}
}
}
case ExPorterSDK.Quote.get_quote(params) do
{:ok, response} ->
# Handle successful response
IO.inspect(response["vehicles"])
{:error, error} ->
# Handle error
IO.inspect(error)
end
Create Order
order_params = %{
request_id: "unique-request-id",
delivery_instructions: %{
instructions_list: [
%{type: "text", description: "handle with care"}
]
},
pickup_details: %{
address: %{
apartment_address: "27",
street_address1: "Main Street",
city: "Bengaluru",
state: "Karnataka",
pincode: "560029",
country: "India",
lat: 12.939391726766775,
lng: 77.62629462844717,
contact_details: %{
name: "Test User",
phone_number: "+911234567890"
}
}
},
drop_details: %{
# Similar structure as pickup_details
}
}
{:ok, order} = ExPorterSDK.Order.create(order_params)
Track Order
{:ok, status} = ExPorterSDK.Order.track("order_id")
Cancel Order
{:ok, response} = ExPorterSDK.Order.cancel("order_id")
Testing
The SDK provides stub implementations for testing. Configure them in your config/test.exs
:
config :ex_porter_sdk,
base_url: "https://api.porter.in",
api_key: "your-api-key",
quote_impl: ExPorterSDK.Quote.Stub,
order_impl: ExPorterSDK.Order.Stub
Or set them temporarily in your tests:
setup do
previous_impls = %{
quote: Application.get_env(:ex_porter_sdk, :quote_impl),
order: Application.get_env(:ex_porter_sdk, :order_impl)
}
Application.put_env(:ex_porter_sdk, :quote_impl, ExPorterSDK.Quote.Stub)
Application.put_env(:ex_porter_sdk, :order_impl, ExPorterSDK.Order.Stub)
on_exit(fn ->
Application.put_env(:ex_porter_sdk, :quote_impl, previous_impls.quote)
Application.put_env(:ex_porter_sdk, :order_impl, previous_impls.order)
end)
:ok
end
Error Handling
All operations return tagged tuples:
{:ok, response}
- Successful operation with response data{:error, reason}
- Failed operation with error details
Common error reasons include:
- Invalid parameters
- Authentication failures
- Network issues
- Resource not found
- Server errors
Links
Summary
Functions
Returns the configured API key for the Porter API.
Returns the configured base URL for the Porter API.
Functions
@spec api_key() :: String.t()
Returns the configured API key for the Porter API.
Raises
RuntimeError if api_key is not configured.
Examples
iex> ExPorterSDK.api_key()
"your-api-key"
@spec base_url() :: String.t()
Returns the configured base URL for the Porter API.
Raises
RuntimeError if base_url is not configured.
Examples
iex> ExPorterSDK.base_url()
"https://api.porter.in"