Steadfast Courier Python SDK Documentation

Welcome to the Steadfast Courier Python SDK documentation. This guide will help you integrate Steadfast courier services into your Python applications.

Getting Started

Installation - Install the SDK and verify setup
Authentication - Configure API credentials
Quick Start - Create your first order

API Reference

Order Management - Create and manage orders
Order Tracking - Track order status
Balance Management - Check account balance
Return Requests - Manage return requests
Payments - View payment information

Guides

Error Handling - Handle errors and exceptions
Examples - Code examples and use cases

Quick Start

1. Install the SDK

pip install steadfast

2. Set Up Credentials

Create a .env file:

STEADFAST_API_KEY=your_api_key
STEADFAST_SECRET_KEY=your_secret_key

3. Initialize Client

from steadfast import SteadfastClient

client = SteadfastClient(
    api_key="your_api_key",
    secret_key="your_secret_key"
)

4. Create an Order

order = client.orders.create(
    invoice="ORD-2024-001",
    recipient_name="John Smith",
    recipient_phone="01234567890",
    recipient_address="House 123, Dhaka",
    cod_amount=1060,
    delivery_type=0
)

print(f"Order created: {order.consignment_id}")
print(f"Tracking code: {order.tracking_code}")

5. Track Order

status = client.tracking.get_status_by_consignment_id(order.consignment_id)
print(f"Status: {status.delivery_status}")

Core Modules

Orders Module

Create and manage courier orders.

# Create single order
order = client.orders.create(...)

# Create bulk orders
response = client.orders.create_bulk([...])

Tracking Module

Track order status using different identifiers.

# By consignment ID
status = client.tracking.get_status_by_consignment_id(123)

# By invoice
status = client.tracking.get_status_by_invoice("ORD-2024-001")

# By tracking code
status = client.tracking.get_status_by_tracking_code("TRACK123")

Balance Module

Check account balance.

balance = client.balance.get_current_balance()
print(f"Balance: {balance.current_balance}")

Return Requests Module

Manage return requests.

# Create return
return_req = client.returns.create(
    identifier=123,
    identifier_type="consignment_id",
    reason="Damaged"
)

# Get return
return_req = client.returns.get(1)

# List returns
returns = client.returns.list()

Payments Module

View payment information.

# List payments
payments = client.payments.list()

# Get payment details
payment = client.payments.get(1)

Exception Handling

The SDK provides specific exceptions for different error scenarios:

from steadfast import (
    SteadfastClient,
    ValidationError,
    NotFoundError,
    AuthenticationError,
    APIError,
    NetworkError,
)

try:
    order = client.orders.create(...)
except ValidationError as e:
    print(f"Invalid input: {e}")
except NotFoundError as e:
    print(f"Not found: {e}")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except APIError as e:
    print(f"API error: {e}")
except NetworkError as e:
    print(f"Network error: {e}")

Common Tasks

Create Order and Track

from steadfast import SteadfastClient

client = SteadfastClient(api_key="key", secret_key="secret")

# Create order
order = client.orders.create(
    invoice="ORD-2024-001",
    recipient_name="John Smith",
    recipient_phone="01234567890",
    recipient_address="House 123, Dhaka",
    cod_amount=1060,
    delivery_type=0
)

# Track order
status = client.tracking.get_status_by_consignment_id(order.consignment_id)
print(f"Status: {status.delivery_status}")

Bulk Order Creation

orders = [
    {
        "invoice": "ORD-2024-001",
        "recipient_name": "John Smith",
        "recipient_phone": "01234567890",
        "recipient_address": "House 123, Dhaka",
        "cod_amount": 1060,
        "delivery_type": 0,
    },
    {
        "invoice": "ORD-2024-002",
        "recipient_name": "Jane Doe",
        "recipient_phone": "01987654321",
        "recipient_address": "Apt 456, Chittagong",
        "cod_amount": 2500,
        "delivery_type": 1,
    },
]

response = client.orders.create_bulk(orders)

for result in response.results:
    if result.status == "success":
        print(f"Order {result.invoice}: {result.consignment_id}")
    else:
        print(f"Order {result.invoice} failed: {result.error}")

Check Balance Before Order

balance = client.balance.get_current_balance()

if balance.current_balance >= 1000:
    order = client.orders.create(...)
else:
    print("Insufficient balance")

Support

For issues and questions:

Check the Error Handling Guide
Review Examples
Contact Steadfast support

License

MIT License - See LICENSE file for details

Version

Current version: 0.3.0

See CHANGELOG for version history.