PHPackages                             nayemuf/steadfast-courier - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. nayemuf/steadfast-courier

ActiveLibrary[API Development](/categories/api)

nayemuf/steadfast-courier
=========================

Laravel package for SteadFast Courier API integration with caching and rate limiting

215↑100%PHP

Since Nov 28Pushed 5mo agoCompare

[ Source](https://github.com/nayemuf/steadfast-courier)[ Packagist](https://packagist.org/packages/nayemuf/steadfast-courier)[ RSS](/packages/nayemuf-steadfast-courier/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Laravel SteadFast Courier Package
=================================

[](#laravel-steadfast-courier-package)

[![Latest Version on Packagist](https://camo.githubusercontent.com/4b3b589e0ab267aa9e80d86cff305ddc3c4d4b83bd24b72d083c3266e73a9e17/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e6179656d75662f7374656164666173742d636f75726965722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/nayemuf/steadfast-courier)[![Total Downloads](https://camo.githubusercontent.com/33d1041cccfd0ac5b5630160602fb5217edffb31868c52789d6fce83655b796e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6e6179656d75662f7374656164666173742d636f75726965722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/nayemuf/steadfast-courier)[![License](https://camo.githubusercontent.com/b35cda859ad2234680b8da0617742b0fb90d9acbb55bc75f3fbf1bf7d81139d3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6e6179656d75662f7374656164666173742d636f75726965722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/nayemuf/steadfast-courier)[![Laravel](https://camo.githubusercontent.com/11ba5d99015522487fdaeafecd4de3c8f5e91bafd16811422ad0af48afd92dde/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302e7825323025374325323031312e7825323025374325323031322e782d6f72616e67652e7376673f7374796c653d666c61742d737175617265)](https://laravel.com)[![PHP Version](https://camo.githubusercontent.com/28fee99128868a1f0862753c10cd99e05553fa5df3a1c6feb24d7d10aacf60f2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6e6179656d75662f7374656164666173742d636f75726965722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/nayemuf/steadfast-courier)

A professional Laravel package for integrating with **SteadFast Courier API**. This package provides a clean, well-structured interface for all SteadFast API endpoints with built-in caching, rate limiting, and comprehensive error handling.

✨ Features
----------

[](#-features)

- ✅ **Complete API Coverage** - All SteadFast Courier API endpoints implemented
- ✅ **API Key Authentication** - Secure authentication with API Key and Secret Key
- ✅ **Rate Limiting** - Built-in protection against API abuse (configurable)
- ✅ **Input Validation** - Comprehensive validation before API calls
- ✅ **Error Handling** - Detailed exception messages with field-level errors
- ✅ **Laravel Best Practices** - Service Provider, Facades, and publishable config
- ✅ **Type Safety** - Complete type hints and PHPDoc documentation
- ✅ **Zero Configuration** - Works out of the box with sensible defaults
- ✅ **Production Ready** - Battle-tested in production environments

📋 Requirements
--------------

[](#-requirements)

- PHP >= 8.2
- Laravel >= 10.0
- Guzzle HTTP Client >= 7.0

📦 Installation
--------------

[](#-installation)

Install the package via Composer:

```
composer require nayemuf/steadfast-courier
```

The package will automatically register its service provider and facade.

⚙️ Configuration
----------------

[](#️-configuration)

### Step 1: Publish Configuration

[](#step-1-publish-configuration)

Publish the configuration file to your `config` directory:

```
php artisan vendor:publish --tag=steadfast-config
```

This will create `config/steadfast.php` in your Laravel application.

### Step 2: Environment Variables

[](#step-2-environment-variables)

Add the following to your `.env` file:

```
STEADFAST_BASE_URL=https://portal.packzy.com/api/v1
STEADFAST_API_KEY=your-api-key
STEADFAST_SECRET_KEY=your-secret-key

# Optional: Webhook Bearer Token
STEADFAST_BEARER_TOKEN=your-generated-bearer-token

# Optional: Rate Limiting
STEADFAST_RATE_LIMIT_ENABLED=true
STEADFAST_RATE_LIMIT_PER_MINUTE=60
```

**Note:** You can obtain your API credentials from the [SteadFast Courier Portal](https://steadfast.com.bd/).

🚀 Usage
-------

[](#-usage)

### Placing an Order

[](#placing-an-order)

```
use Nayemuf\SteadfastCourier\Facades\SteadfastCourier;

$orderData = [
    'invoice' => 'ORD-123456',
    'recipient_name' => 'John Doe',
    'recipient_phone' => '01712345678',
    'recipient_address' => 'House 44, Road 2/A, Dhanmondi, Dhaka 1209',
    'cod_amount' => 1000.00,
    'note' => 'Handle with care',
    'recipient_email' => 'john@example.com', // Optional
    'alternative_phone' => '01812345678', // Optional
    'item_description' => 'Product description', // Optional
    'total_lot' => 1, // Optional
    'delivery_type' => 0, // Optional: 0 = home delivery, 1 = hub pickup
];

try {
    $response = SteadfastCourier::order()->placeOrder($orderData);

    // Access response data
    $consignmentId = $response['consignment']['consignment_id'];
    $trackingCode = $response['consignment']['tracking_code'];

    echo "Order created! Consignment ID: {$consignmentId}, Tracking: {$trackingCode}";
} catch (\Nayemuf\SteadfastCourier\Exceptions\SteadfastException $e) {
    // Handle error
    logger()->error('SteadFast order creation failed', [
        'message' => $e->getMessage(),
        'errors' => $e->getErrors(),
    ]);
}
```

**Response:**

```
{
    "status": 200,
    "message": "Consignment has been created successfully.",
    "consignment": {
        "consignment_id": 1424107,
        "invoice": "ORD-123456",
        "tracking_code": "15BAEB8A",
        "recipient_name": "John Doe",
        "recipient_phone": "01712345678",
        "recipient_address": "House 44, Road 2/A, Dhanmondi, Dhaka 1209",
        "cod_amount": 1000.00,
        "status": "in_review",
        "created_at": "2021-03-21T07:05:31.000000Z"
    }
}
```

### Bulk Order Creation

[](#bulk-order-creation)

Create up to 500 orders in a single request:

```
$orders = [
    [
        'invoice' => 'ORD-001',
        'recipient_name' => 'John Doe',
        'recipient_phone' => '01712345678',
        'recipient_address' => 'House 44, Road 2/A, Dhanmondi, Dhaka 1209',
        'cod_amount' => 1000.00,
    ],
    [
        'invoice' => 'ORD-002',
        'recipient_name' => 'Jane Smith',
        'recipient_phone' => '01812345678',
        'recipient_address' => 'House 55, Road 3/B, Gulshan, Dhaka 1212',
        'cod_amount' => 1500.00,
    ],
];

$response = SteadfastCourier::order()->placeBulkOrders($orders);

// Response contains array of results for each order
foreach ($response as $result) {
    if ($result['status'] === 'success') {
        echo "Order {$result['invoice']} created: {$result['tracking_code']}\n";
    } else {
        echo "Order {$result['invoice']} failed\n";
    }
}
```

### Checking Delivery Status

[](#checking-delivery-status)

```
// By Consignment ID
$status = SteadfastCourier::status()->getStatusByConsignmentId(1424107);

// By Invoice ID
$status = SteadfastCourier::status()->getStatusByInvoice('ORD-123456');

// By Tracking Code
$status = SteadfastCourier::status()->getStatusByTrackingCode('15BAEB8A');

// Response:
// {
//     "status": 200,
//     "delivery_status": "in_review"
// }
```

### Checking Current Balance

[](#checking-current-balance)

```
$balance = SteadfastCourier::balance()->getCurrentBalance();

// Response:
// {
//     "status": 200,
//     "current_balance": 5000.00
// }
```

### Return Requests

[](#return-requests)

```
// Create return request
$returnRequest = SteadfastCourier::return()->createReturnRequest([
    'consignment_id' => 1424107, // or 'invoice' => 'ORD-123456' or 'tracking_code' => '15BAEB8A'
    'reason' => 'Customer requested return', // Optional
]);

// Get single return request
$return = SteadfastCourier::return()->getReturnRequest(1);

// Get all return requests
$returns = SteadfastCourier::return()->getReturnRequests();
```

### Payments

[](#payments)

```
// Get payments list
$payments = SteadfastCourier::payment()->getPayments();

// Get single payment with consignments
$payment = SteadfastCourier::payment()->getPayment(123);
```

### Police Stations

[](#police-stations)

```
$policeStations = SteadfastCourier::policeStation()->getPoliceStations();
```

📚 Complete API Reference
------------------------

[](#-complete-api-reference)

### Order API

[](#order-api)

#### `placeOrder(array $orderData): array`

[](#placeorderarray-orderdata-array)

Place a single order with SteadFast Courier.

**Required Parameters:**

- `invoice` (string): Unique invoice ID (alphanumeric with hyphens/underscores)
- `recipient_name` (string): Recipient name (max 100 characters)
- `recipient_phone` (string): Recipient phone (exactly 11 digits)
- `recipient_address` (string): Recipient address (max 250 characters)
- `cod_amount` (float): Cash on delivery amount (>= 0)

**Optional Parameters:**

- `alternative_phone` (string): Alternative phone (11 digits)
- `recipient_email` (string): Recipient email
- `note` (string): Delivery instructions
- `item_description` (string): Item description
- `total_lot` (int): Total lot of items
- `delivery_type` (int): 0 = home delivery, 1 = hub pickup

#### `placeBulkOrders(array $orders): array`

[](#placebulkordersarray-orders-array)

Place multiple orders (max 500) in a single request. Each order follows the same structure as `placeOrder()`.

### Status API

[](#status-api)

#### `getStatusByConsignmentId(int $consignmentId): array`

[](#getstatusbyconsignmentidint-consignmentid-array)

Get delivery status by consignment ID.

#### `getStatusByInvoice(string $invoice): array`

[](#getstatusbyinvoicestring-invoice-array)

Get delivery status by invoice ID.

#### `getStatusByTrackingCode(string $trackingCode): array`

[](#getstatusbytrackingcodestring-trackingcode-array)

Get delivery status by tracking code.

### Balance API

[](#balance-api)

#### `getCurrentBalance(): array`

[](#getcurrentbalance-array)

Get current account balance.

### Return API

[](#return-api)

#### `createReturnRequest(array $data): array`

[](#createreturnrequestarray-data-array)

Create a return request. Requires one of: `consignment_id`, `invoice`, or `tracking_code`.

#### `getReturnRequest(int $id): array`

[](#getreturnrequestint-id-array)

Get single return request by ID.

#### `getReturnRequests(): array`

[](#getreturnrequests-array)

Get all return requests.

### Payment API

[](#payment-api)

#### `getPayments(): array`

[](#getpayments-array)

Get payments list.

#### `getPayment(int $paymentId): array`

[](#getpaymentint-paymentid-array)

Get single payment with consignments.

### Police Station API

[](#police-station-api)

#### `getPoliceStations(): array`

[](#getpolicestations-array)

Get police stations list.

🔒 Error Handling
----------------

[](#-error-handling)

The package throws `SteadfastException` for API errors with detailed information:

```
use Nayemuf\SteadfastCourier\Exceptions\SteadfastException;

try {
    $response = SteadfastCourier::order()->placeOrder($orderData);
} catch (SteadfastException $e) {
    // Get error message
    $message = $e->getMessage();

    // Get field-level errors (if available)
    $errors = $e->getErrors();

    // Get HTTP status code
    $code = $e->getCode();

    // Log or handle error
    logger()->error('SteadFast API Error', [
        'message' => $message,
        'errors' => $errors,
        'code' => $code,
    ]);
}
```

⚡ Caching & Rate Limiting
-----------------------------

[](#-caching--rate-limiting)

The package includes built-in caching and rate limiting to optimize API usage:

### Rate Limiting

[](#rate-limiting)

- **Default**: 60 requests per minute
- **Configurable**: Set `STEADFAST_RATE_LIMIT_PER_MINUTE` in your `.env`
- **Automatic**: Prevents exceeding API limits

### Caching

[](#caching)

API responses can be cached to reduce API calls. Configure in `config/steadfast.php`:

```
'cache' => [
    'prefix' => 'steadfast_courier_',
    'token_ttl' => 432000, // 5 days
],
```

✅ Validation Rules
------------------

[](#-validation-rules)

The package validates all data before sending to the API to prevent errors:

FieldRules`invoice`Required, alphanumeric with hyphens/underscores only`recipient_name`Required, max 100 characters`recipient_phone`Required, exactly 11 digits`recipient_address`Required, max 250 characters`cod_amount`Required, numeric, >= 0`alternative_phone`Optional, exactly 11 digits if provided`recipient_email`Optional, valid email format`note`Optional`item_description`Optional`total_lot`Optional, numeric`delivery_type`Optional, 0 or 1📝 Delivery Statuses
-------------------

[](#-delivery-statuses)

Possible delivery statuses returned by the API:

StatusDescription`pending`Not yet delivered or cancelled`delivered_approval_pending`Delivered, awaiting admin approval`partial_delivered_approval_pending`Partially delivered, awaiting approval`cancelled_approval_pending`Cancelled, awaiting approval`unknown_approval_pending`Unknown state, needs support intervention`delivered`Delivered and balance updated`partial_delivered`Partially delivered and balance updated`cancelled`Cancelled and balance updated`hold`On hold`in_review`Order placed, under review`unknown`Unknown status, need contact with support team🔧 Advanced Usage
----------------

[](#-advanced-usage)

### Using Without Facade

[](#using-without-facade)

You can also use the package without the facade:

```
use Nayemuf\SteadfastCourier\SteadfastCourier;

$courier = new SteadfastCourier(
    config('steadfast.api_key'),
    config('steadfast.secret_key'),
    config('steadfast.base_url')
);

$response = $courier->order()->placeOrder($orderData);
```

### Custom Base URL

[](#custom-base-url)

You can override the base URL for custom endpoints:

```
$courier = new SteadfastCourier(
    'your-api-key',
    'your-secret-key',
    'https://custom-url.com/api/v1'
);
```

🧪 Testing
---------

[](#-testing)

The package is fully tested and ready for production use. For testing in your application:

```
// In your tests
use Nayemuf\SteadfastCourier\Facades\SteadfastCourier;

// Mock the facade if needed
SteadfastCourier::shouldReceive('order->placeOrder')
    ->andReturn(['status' => 200, 'consignment' => [...]]);
```

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please follow these guidelines:

1. **Follow PSR-4** autoloading standards
2. **Adhere to SteadFast's official API documentation** - Always refer to the latest API docs
3. **Write clear, documented code** - Add PHPDoc comments
4. **Add tests** for new features
5. **Update README and CHANGELOG** when adding features
6. **Follow Laravel conventions** - Use Laravel's coding standards

### Development Setup

[](#development-setup)

```
# Clone the repository
git clone https://github.com/nayemuf/steadfast-courier.git
cd steadfast-courier

# Install dependencies
composer install

# Run tests
composer test
```

📄 License
---------

[](#-license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

👤 Author
--------

[](#-author)

### Nayem Uddin

[](#nayem-uddin)

- Email:
- LinkedIn: [Connect with me](https://www.linkedin.com/in/nayemuf/)

🙏 Acknowledgments
-----------------

[](#-acknowledgments)

- [SteadFast Courier Limited](https://steadfast.com.bd/) for providing the API
- Laravel community for the amazing framework
- All contributors who help improve this package

📚 Additional Resources
----------------------

[](#-additional-resources)

- [SteadFast Courier Official Website](https://steadfast.com.bd/)
- [SteadFast API Documentation](https://portal.packzy.com/api/v1)
- [Laravel Documentation](https://laravel.com/docs)

🐛 Reporting Issues
------------------

[](#-reporting-issues)

If you encounter any issues or have suggestions, please open an issue on [GitHub](https://github.com/nayemuf/steadfast-courier/issues).

⭐ Support
---------

[](#-support)

If this package helps you, please consider giving it a ⭐ on [Packagist](https://packagist.org/packages/nayemuf/steadfast-courier) or [GitHub](https://github.com/nayemuf/steadfast-courier).

💬 Issues
--------

[](#-issues)

For issues, questions, or feature requests, please open an issue on [GitHub](https://github.com/nayemuf/pathao-courier/issues).
-------------------------------------------------------------------------------------------------------------------------------

[](#for-issues-questions-or-feature-requests-please-open-an-issue-on-github)

###  Health Score

20

—

LowBetter than 14% of packages

Maintenance48

Moderate activity, may be stable

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/2da5217a515cbf963e81d1f6112d67aa71a9fe43b181ad20235346081fb26d38?d=identicon)[nayemuf](/maintainers/nayemuf)

---

Top Contributors

[![nayemuf](https://avatars.githubusercontent.com/u/119859626?v=4)](https://github.com/nayemuf "nayemuf (2 commits)")

### Embed Badge

![Health badge](/badges/nayemuf-steadfast-courier/health.svg)

```
[![Health](https://phpackages.com/badges/nayemuf-steadfast-courier/health.svg)](https://phpackages.com/packages/nayemuf-steadfast-courier)
```

###  Alternatives

[stripe/stripe-php

Stripe PHP Library

4.0k143.3M480](/packages/stripe-stripe-php)[twilio/sdk

A PHP wrapper for Twilio's API

1.6k92.9M272](/packages/twilio-sdk)[knplabs/github-api

GitHub API v3 client

2.2k15.8M187](/packages/knplabs-github-api)[facebook/php-business-sdk

PHP SDK for Facebook Business

90121.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php

PHP wrapper for the Meilisearch API

73813.7M114](/packages/meilisearch-meilisearch-php)[google/gax

Google API Core for PHP

263103.1M454](/packages/google-gax)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)