README

roadmap.

📦 PostEx Laravel SDK

Laravel package for PostEx COD API integration Supports order creation, delivery validation, tracking, payment status, pickup management, and more.

Compatible with Laravel 9, 10, 11 API Version: PostEx v4.1.9

🚀 Features

• ✅ Check if a city/address is deliverable
• 📦 Create COD orders
• 🚚 Track orders (single & bulk)
• 🧾 Generate airway bill & load sheet
• 🏬 Manage pickup addresses
• ❌ Cancel orders
• 💰 Check payment & settlement status
• 📝 Shipper advice (retry / return)
• 📊 List orders & statuses
• 🧩 Laravel Facade support
• 🔍 PSR-4, auto-discovery enabled

📌 Requirements

Requirement	Version
PHP	≥ 8.0
Laravel	9.x / 10.x / 11.x
PostEx API Token	Required

📥 Installation

Install via Composer:

composer require cw-alihyder/postex-laravel

⚙️ Configuration

Publish the config file:

php artisan vendor:publish --tag=postex-config

This will create:

config/postex.php

🔐 Environment Variables

Add the following to your .env:

POSTEX_TOKEN=your_postex_api_token_here
POSTEX_BASE_URL=https://api.postex.pk/services/integration/api

🧠 Usage Overview

You can use the package via:

• ✅ Facade (PostEx::)
• ✅ Dependency Injection

🏙 Check City Deliverability

use PostEx;

$isDeliverable = PostEx::isCityDeliverable('Lahore');

if (!$isDeliverable) {
    throw new Exception('Delivery not available in this city');
}

📦 Create Order (COD)

use PostEx;

$response = PostEx::createOrder([
    'orderRefNumber'   => 'ORD-10001',
    'invoicePayment'   => 2500,
    'orderDetail'      => '1x Mobile Phone',
    'customerName'     => 'Ali Khan',
    'customerPhone'    => '03001234567',
    'deliveryAddress'  => 'Model Town, Lahore',
    'cityName'         => 'Lahore',
    'invoiceDivision'  => 1,
    'items'            => 1,
    'orderType'        => 'Normal', // Normal | Reverse | Replacement
]);

$trackingNumber = $response['dist']['trackingNumber'];

🚚 Track Order

Single Tracking

PostEx::track('CX-XXXXXXXXXXX');

Bulk Tracking

PostEx::bulkTrack([
    'CX-XXXX1',
    'CX-XXXX2',
]);

💰 Payment Status

PostEx::paymentStatus('CX-XXXXXXXXXXX');

❌ Cancel Order

PostEx::cancelOrder('CX-XXXXXXXXXXX');

🏬 Pickup Address Management

List Pickup Addresses

PostEx::listPickupAddresses('Lahore');

Create Pickup Address

PostEx::createPickupAddress([
    'address' => 'Warehouse #12',
    'addressTypeId' => 2, // 1 Return, 2 Pickup
    'cityName' => 'Lahore',
    'contactPersonName' => 'Store Manager',
    'phone1' => '03001234567',
    'phone2' => '03007654321',
]);

🧾 Generate Load Sheet

PostEx::generateLoadSheet([
    'CX-XXXX1',
    'CX-XXXX2'
], 'Main Warehouse');

📄 Generate Airway Bill (PDF)

PostEx::getAirwayBill([
    'CX-XXXX1',
    'CX-XXXX2'
]);

⚠️ Max 10 tracking numbers per request (PostEx limitation)

📝 Shipper Advice

Save Advice

PostEx::saveShipperAdvice(
    'CX-XXXXXXXXXXX',
    1, // 1 = Return Requested, 2 = Retry Attempt
    'Customer not available'
);

Get Advice History

PostEx::getShipperAdvice('CX-XXXXXXXXXXX');

📊 List Orders

PostEx::listOrders(
    0, // 0 = All statuses
    '2025-01-01',
    '2025-01-31'
);

🧪 Error Handling

All API responses follow PostEx standard format:

[
  'statusCode' => '200',
  'statusMessage' => 'SUCCESSFULLY OPERATED',
  'dist' => [...]
]

You should always check statusCode before trusting the response.

🧾 Versioning Policy (SemVer)

This package follows Semantic Versioning:

MAJOR.MINOR.PATCH

Examples:

• 1.0.0 → Initial stable release
• 1.1.0 → New features (backward-compatible)
• 1.1.1 → Bug fixes
• 2.0.0 → Breaking changes

🗺 Roadmap

• Automatic retries with backoff
• Laravel logging integration
• Queue-ready async support
• Unit & feature tests
• Rate-limit handling
• Webhook handler (future)

🧑‍💻 Author

Ali Hyder 📧 cw.alihyder@gmail.com

📜 License

MIT License © 2025 You are free to use, modify, and distribute.

⭐ Support

If this package helps you, please ⭐ star the repository on GitHub.