steadfast-courier / steadfast-courier-laravel-package
A complate Laravel package for SteadFast Courier Limited
Fund package maintenance!
AmadulHaque
Installs: 1 363
Dependents: 0
Suggesters: 0
Security: 0
Stars: 11
Watchers: 1
Forks: 15
Open Issues: 0
pkg:composer/steadfast-courier/steadfast-courier-laravel-package
Requires
- php: ^7.2|^8.0
- guzzlehttp/guzzle: ^7.2
- illuminate/contracts: ^6.0|^7.0|^8.0|^9.0|^10.0|^11.0|^12.0
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- laravel/pint: ^1.14
- nunomaduro/collision: ^8.1.1||^7.10.0
- orchestra/testbench: ^9.0.0||^8.22.0
- pestphp/pest: ^2.34
- pestphp/pest-plugin-arch: ^2.7
- pestphp/pest-plugin-laravel: ^2.3
README
A complate Laravel package for SteadFast Courier Limited
This is a Laravel/PHP package for Steadfast Courier System. This package can be used in laravel projects. You can use this package for headless/rest implementation as well as blade or regular mode development. We created this package while working for a project and thought to made it release for all so that it helps. This package is available as regular php composer package.
✨ Features
🚀 Installation
You can install the package via composer:
composer require steadfast-courier/steadfast-courier-laravel-package
You can publish the config file with:
php artisan vendor:publish --tag="steadfast-courier-config"
After publish config file setup your credential. you can see this in your config directory steadfast-courier.php file
"base_url" => env('STEADFAST_BASE_URL', 'https://portal.steadfast.com.bd/api/v1'), "api_key" => env('STEADFAST_API_KEY', 'your-api-key'), "secret_key" => env('STEADFAST_SECRET_KEY', 'your-secret-key'), "webhook_bearer_token" => env('STEADFAST_BEARER_TOKEN', 'your-generated-token'),
⚙️ Set .env configuration
STEADFAST_BASE_URL= "https://portal.steadfast.com.bd/api/v1" STEADFAST_API_KEY = "your-api-key" STEADFAST_SECRET_KEY ="your-secret-key"
📬 1. Placing an order
use SteadFast\SteadFastCourierLaravelPackage\Facades\SteadfastCourier;
Use this namespace at the top of the php class file
$orderData = [ 'invoice' => '123456', 'recipient_name' => 'John Doe', 'recipient_phone' => '01234567890', 'recipient_address' => 'Fla# A1,House# 17/1, Road# 3/A, Dhanmondi,Dhaka-1209', 'cod_amount' => 1000, 'note' => 'Handle with care' ]; $response = SteadfastCourier::placeOrder($orderData);
Response:
{ "status": 200, "message": "Consignment has been created successfully.", "consignment": { "consignment_id": 1424107, "invoice": "Aa12-das4", "tracking_code": "15BAEB8A", "recipient_name": "John Doe", "recipient_phone": "01234567890", "recipient_address": "Fla# A1,House# 17/1, Road# 3/A, Dhanmondi,Dhaka-1209", "cod_amount": 1000, "status": "in_review", "note": "Deliver within 3PM", "created_at": "2021-03-21T07:05:31.000000Z", "updated_at": "2021-03-21T07:05:31.000000Z" } }
📦 2. Bulk Order Create
use SteadFast\SteadFastCourierLaravelPackage\Facades\SteadfastCourier;
Use this is at the top of the php class file
$ordersData = [ [ 'invoice' => '123456', 'recipient_name' => 'John Doe', 'recipient_phone' => '01234567890', 'recipient_address' => '123 Main St', 'cod_amount' => 1000, 'note' => 'Handle with care' ],[ 'invoice' => '789012', 'recipient_name' => 'Jane Smith', 'recipient_phone' => '09876543210', 'recipient_address' => '456 Elm St', 'cod_amount' => 1500, 'note' => 'Fragile' ] ]; $response = SteadfastCourier::bulkCreateOrders($ordersData);
Response:
[ { "invoice": "230822-1", "recipient_name": "John Doe", "recipient_address": "House 44, Road 2/A, Dhanmondi, Dhaka 1209", "recipient_phone": "0171111111", "cod_amount": "0.00", "note": null, "consignment_id": 11543968, "tracking_code": "B025A038", "status": "success" }, { "invoice": "230822-1", "recipient_name": "John Doe", "recipient_address": "House 44, Road 2/A, Dhanmondi, Dhaka 1209", "recipient_phone": "0171111111", "cod_amount": "0.00", "note": null, "consignment_id": 11543969, "tracking_code": "B025A1DC", "status": "success" } ]
If there is any error in your data or network, the response will be like this.
Response:
[ { "invoice": "230822-1", "recipient_name": "John Doe", "recipient_address": "House 44, Road 2/A, Dhanmondi, Dhaka 1209", "recipient_phone": "0171111111", "cod_amount": "0.00", "note": null, "consignment_id": null, "tracking_code": null, "status": "error" }, ]
🔍 3. Checking Delivery Status
There are three way to check Delivery Status, and each have same response like below.
use SteadFast\SteadFastCourierLaravelPackage\Facades\SteadfastCourier;
Use this at the top of the php class file
// Way 1: Check Delivery Status using Consignment ID $consignmentId = 123456; $response1 = SteadfastCourier::checkDeliveryStatusByConsignmentId($consignmentId); // Way 2: Check Delivery Status using Invoice ID $invoice = "230822-1"; $response3 = SteadfastCourier::checkDeliveryStatusByInvoiceId($invoice); // Way 3: Check Delivery Status using Tracking Code $trackingCode = "B025A3FA"; $response2 = SteadfastCourier::checkDeliveryStatusByTrackingCode($trackingCode);
Response:
{ "status": 200, "delivery_status": "in_review" }
Delivery Statuses
Here are the possible delivery statuses returned by the Steadfast Courier API along with their descriptions:
Status | Meaning |
---|---|
pending | Not yet delivered or canceled |
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 the support team |
[ pending, delivered_approval_pending, partial_delivered_approval_pending, cancelled_approval_pending, unknown_approval_pending, delivered, partial_delivered, cancelled, hold, in_review, unknown ]
You can use these statuses to track the progress of your consignments and take appropriate actions.
💰 4. Checking Current Balance
use SteadFast\SteadFastCourierLaravelPackage\Facades\SteadfastCourier;
Use this at the top of the php class file
$response = SteadfastCourier::getCurrentBalance();
Response:
{ "status": 200, "current_balance": 0 }
🔁 5. Webhook Integration
SteadFast Webhook wants Callback Url
and Auth Token(Bearer)
Callback Url: SteadFast will use this URL to announce any changes to the parcel status. Auth Token(Bearer): For Authentication.
Make a Api Route
Route::post('/staedfast-webhook', [SteadFastWebhookController::class, 'handleSteadFastWebhook']);
Set Auth Token(Bearer) in .env
STEADFAST_BEARER_TOKEN ="your-generated-bearer-token"
Controller: SteadFastWebhookController
or your Own made Controller
public function handleSteadFastWebhook(Request $request) { $payload = $request->all(); $token = $request->header('Authorization'); // Check if Bearer token is valid if ($token !== 'Bearer '. config('steadfast-courier.webhook_bearer_token')) { return response()->json(['error' => 'Unauthorized'], 401); } try { $this->validatePayload($payload); $this->processPayload($payload); return response()->json(['status' => 'success'], 200); } catch (\Throwable $th) { return response()->json(['error' => $th->getMessage()], 400); } return response()->json(['message' => 'Webhook received'], 200); } private function validatePayload($payload) { $properties = [ 'consignment_id', 'invoice', 'status', 'cod_amount', 'updated_at', ]; $missingProperties = array_diff($properties, array_keys($payload)); if ($missingProperties) { abort(400, 'Missing required properties: ' . implode(', ', $missingProperties)); } } private function processPayload($payload) { $consignment_id = $payload['consignment_id']; $orderStatus = $payload['status']; /** *| WRITE YOUR CODE *| FOR HANDLE THE COURIER STATUS *| OF YOUR APPLICATION */ }
📞 Support
For any issues or questions related to this package, please open an issue on GitHub.
👥 Credits
📄 License
The MIT License (MIT). Please see License File for more information.