Order Management API

Overview

The Order module handles creation and management of courier orders. It supports both single order creation and bulk operations (up to 500 orders).

Methods

create()

Create a single order.

Signature:

def create(
    invoice: str,
    recipient_name: str,
    recipient_phone: str,
    recipient_address: str,
    cod_amount: float,
    delivery_type: int,
    note: Optional[str] = None
) -> Order

Parameters:

• invoice (str): Unique invoice identifier (alphanumeric, hyphens, underscores)

• recipient_name (str): Recipient name (max 100 characters)

• recipient_phone (str): Phone number (exactly 11 digits)

• recipient_address (str): Delivery address (max 250 characters)

• cod_amount (float): Cash on delivery amount (>= 0)

• delivery_type (int): 0 for home delivery, 1 for point delivery

• note (str, optional): Additional notes

Returns:

• Order: Order object with consignment_id, tracking_code, and status

Raises:

• ValidationError: If any input validation fails

• APIError: If API returns an error

• NetworkError: If network error occurs

Example:

from steadfast import SteadfastClient

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

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,
    note="Handle with care"
)

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

create_bulk()

Create multiple orders in a single request (up to 500).

Signature:

def create_bulk(orders: List[Dict[str, Any]]) -> BulkOrderResponse

Parameters:

• orders (list): List of order dictionaries with same fields as create()

Returns:

• BulkOrderResponse: Contains list of BulkOrderResult with individual success/error status

Raises:

• ValidationError: If validation fails (empty list, > 500 items, invalid fields)

• APIError: If API returns an error

• NetworkError: If network error occurs

Example:

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}")

Validation Rules

Field	Rule	Example
invoice	Alphanumeric, hyphens, underscores	ORD-2024-001
recipient_name	Max 100 characters	John Smith
recipient_phone	Exactly 11 digits	01234567890
recipient_address	Max 250 characters	House 123, Dhaka
cod_amount	Numeric, >= 0	1060
delivery_type	0 or 1	0

Error Handling

from steadfast import SteadfastClient, ValidationError, APIError, NetworkError

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

try:
    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,
    )
except ValidationError as e:
    print(f"Validation error: {e}")
except APIError as e:
    print(f"API error: {e}")
except NetworkError as e:
    print(f"Network error: {e}")