README

A clean, structured PHP SDK for interacting with the Shipway API, providing support for order management, courier services, rate calculation, tracking, and manifests.

This SDK is designed as a Composer package, following PSR-4 autoloading and a clear separation of concerns (Config → Client → Resources → Models).

📦 Installation

Install via Composer:

composer require mimicak/shipway-php-sdk

Or include it manually by adding it to your composer.json.

🔧 Requirements

• PHP >= 7.4
• Composer
• cURL enabled

🧠 Architecture Overview

The SDK is structured into logical layers:

src/
├── Client          # HTTP & response handling
├── Config          # API configuration & endpoints
├── Exceptions      # Domain-specific exceptions
├── Models
│   ├── Request     # Request DTOs
│   ├── Response    # Response DTOs
│   └── Core models (Order, Address, Product, etc.)
├── Resources       # API feature modules
└── Shipway.php     # SDK entry point

🚀 Quick Start

1️⃣ Create Configuration

use Shipway\Config\Configuration;

$config = new Configuration([
    'api_key' => 'YOUR_API_KEY',
    'base_url' => 'https://app.shipway.com/api'
]);

2️⃣ Initialize SDK

use Shipway\Shipway;

$shipway = new Shipway($config);

The Shipway class is the main entry point. All API interactions go through resource accessors.

📦 Resources & Usage

🧾 Orders

$orders = $shipway->orders();

Supported operations:

• Create order
• Fetch order details
• Fetch order list
• Cancel shipment
• Generate manifest

Example:

use Shipway\Models\Request\ShipmentBooking\GetOrdersRequest;

$request = new GetOrdersRequest([
    'from_date' => '2025-01-01',
    'to_date'   => '2025-01-31'
]);

$response = $shipway->orders()->getOrders($request);

🚚 Courier Services

$courier = $shipway->courier();

Supported operations:

• Get courier list
• Rate calculation
• Pincode serviceability
• Shipment tracking

Example – Rate Calculation:

use Shipway\Models\Request\Carriers\GetCarrierRates;

$request = new GetCarrierRates([
    'pickup_pincode'   => '560001',
    'delivery_pincode' => '110001',
    'weight'           => 1.5,
    'cod'              => true
]);

$response = $shipway->courier()->getRates($request);

🏭 Warehouse

$warehouse = $shipway->warehouse();

Handles warehouse-related Shipway APIs such as listing or configuration (based on API availability).

📚 Models

Core Models

• Order
• OrderListItem
• Address
• Product
• ShipmentStatusScan

Request Models

Located in:

src/Models/Request/

These classes encapsulate API request payloads and prevent passing raw arrays.

Response Models

Located in:

src/Models/Response/

These map API responses into typed PHP objects.

⚠️ Exception Handling

All exceptions extend Shipway\Exceptions\ShipwayException.

Possible exceptions include:

• AuthenticationException
• ValidationException
• RateLimitException
• NetworkException
• ConfigurationException
• ApiException
• WebhookException

Example:

try {
    $shipway->orders()->getOrders($request);
} catch (\Shipway\Exceptions\ShipwayException $e) {
    echo $e->getMessage();
}

🔐 Configuration Errors

If the SDK is misconfigured (missing API key, invalid base URL), a ConfigurationException is thrown during initialization or request execution.

🧪 Examples

The examples/ directory is reserved for future usage samples and integration demos.

🧩 Extensibility

• All API modules extend AbstractResource
• HTTP logic is centralized in HttpClient
• Response parsing is handled by ResponseHandler
• Exception mapping is centralized in ExceptionFactory

This makes the SDK easy to extend without breaking existing functionality.

📄 License

MIT License.

🤝 Contributing

Pull requests are welcome. Please ensure:

• PSR-12 compliance
• Typed models for requests/responses
• No breaking changes without version bumps

📬 Support

For issues, feature requests, or API changes, open an issue on the repository.