Accessing Shipping Hub

1. Log in to your Keddily admin panel.
2. Click Shipping Hub from the left sidebar.
3. You'll see a list of available shipping providers grouped by region.
4. Click Configure on any provider to set up credentials.

Obtaining API credentials

Each provider has different steps to obtain API credentials. The configuration form displays provider-specific instructions.

Bosta

1. Log in to your Bosta dashboard.
2. Navigate to Settings > API.
3. Generate a new API key and secret.
4. Copy the credentials and paste them in the Keddily configuration form.

Aramex

1. Contact Aramex to obtain your shipping account credentials.
2. You'll receive: Account Number, Username, Password, and PIN code.
3. Enter these credentials in the Keddily configuration form.

Other providers

For SMSA, Ajex, Fetchr, DHL, FedEx, and others, visit their developer portals or contact their support team to obtain API credentials. The configuration form will show specific field requirements for each provider.

Entering credentials in Keddily

1. Click Configure on the provider you want to connect.
2. The configuration form shows dynamic fields based on the provider's schema.
3. Fill in required fields (marked with *).
4. For password fields, existing values are masked for security. Leave blank to keep existing credentials.
5. Set Commission Rate (%) — this is the platform fee for shipping transactions.
6. Toggle Active to enable this provider for your store.
7. Click Save Configuration.

Testing the connection

1. After saving credentials, the provider card shows a connection status.
2. Connected — green indicator means credentials are valid.
3. Not Connected — red indicator means credentials need verification.
4. Click Test Connection (if available) to verify API access.
5. If connection fails, double-check your credentials and try again.

Payload structure

To create a shipment, you need to provide a structured payload containing sender, recipient, package details, COD amount, and order reference. The following fields are required:

{
  "sender": {
    "name": "Store Name",
    "phone": "+201234567890",
    "email": "store@example.com",
    "address": "123 Main Street",
    "city": "Cairo",
    "country": "EG",
    "postal_code": "11511"
  },
  "recipient": {
    "name": "Customer Name",
    "phone": "+201098765432",
    "email": "customer@example.com",
    "address": "456 Customer Road",
    "city": "Alexandria",
    "country": "EG",
    "postal_code": "21500"
  },
  "package": {
    "weight": 1.5,
    "length": 20,
    "width": 15,
    "height": 10,
    "description": "Electronics - Smartphone"
  },
  "cod_amount": 2500.00,
  "currency": "EGP",
  "reference": "ORD-2024-001234",
  "provider": "bosta"
}

Code examples

Below is a PHP/Laravel example demonstrating how to create a shipment using the Shipping Hub adapter system:

use App\Services\Shipping\ShippingAdapterFactory;
use App\Services\Shipping\Adapters\BostaAdapter;

// Get the authenticated user
$user = auth()->user();

// Instantiate the adapter factory
$adapterFactory = new ShippingAdapterFactory($user);

// Get the Bosta adapter (or any configured provider)
$adapter = $adapterFactory->getAdapter('bosta');

if (!$adapter) {
    throw new \Exception('Bosta provider not configured');
}

// Prepare shipment data
$shipmentData = [
    'sender' => [
        'name' => $user->shop_name,
        'phone' => $user->phone,
        'email' => $user->email,
        'address' => $user->address,
        'city' => $user->city,
        'country' => 'EG',
        'postal_code' => $user->postal_code ?? '11511'
    ],
    'recipient' => [
        'name' => $order->customer_name,
        'phone' => $order->customer_phone,
        'email' => $order->customer_email,
        'address' => $order->shipping_address,
        'city' => $order->shipping_city,
        'country' => $order->shipping_country,
        'postal_code' => $order->shipping_postal_code
    ],
    'package' => [
        'weight' => $order->total_weight,
        'length' => $order->package_length ?? 20,
        'width' => $order->package_width ?? 15,
        'height' => $order->package_height ?? 10,
        'description' => 'Order #' . $order->order_number
    ],
    'cod_amount' => $order->payment_method === 'cod' ? $order->total : 0,
    'currency' => $order->currency_code,
    'reference' => $order->order_number,
    'provider' => 'bosta'
];

// Create the shipment
try {
    $response = $adapter->createShipment($shipmentData);
    
    // Store the tracking information
    $order->tracking_number = $response['tracking_number'];
    $order->shipping_cost = $response['shipping_cost'];
    $order->estimated_delivery = $response['estimated_delivery'];
    $order->status = 'processing';
    $order->save();
    
    return response()->json([
        'success' => true,
        'tracking_number' => $response['tracking_number'],
        'label_url' => $response['label_url']
    ]);
    
} catch (\Exception $e) {
    return response()->json([
        'success' => false,
        'error' => $e->getMessage()
    ], 500);
}

Response handling

When a shipment is successfully created, the provider returns a response containing tracking information and shipping details:

{
  "success": true,
  "tracking_number": "BOS-1234567890",
  "shipping_cost": 45.50,
  "currency": "EGP",
  "estimated_delivery": "2024-01-25",
  "label_url": "https://provider.example.com/labels/BOS-1234567890.pdf",
  "provider_reference": "PROV-987654321"
}

Success response fields:

• tracking_number — Unique tracking number for the shipment
• shipping_cost — Cost charged by the provider
• currency — Currency of the shipping cost
• estimated_delivery — Expected delivery date
• label_url — URL to download/print the shipping label
• provider_reference — Internal reference from the provider

Error handling:

If the shipment creation fails, the adapter throws an exception with details about the error:

{
  "success": false,
  "error": "Invalid recipient address",
  "details": "Postal code format is incorrect for the selected country"
}

Common error scenarios:

• Missing configuration — Provider credentials not configured
• Invalid address — Recipient address format is incorrect
• Unsupported destination — Provider doesn't ship to the destination country
• COD limit exceeded — COD amount exceeds provider's maximum
• API rate limit — Too many requests to provider API
• Authentication failed — Invalid API credentials

Step-by-step workflow

The complete order-to-shipment flow from checkout to label generation:

1. Order placement — Customer completes checkout on your storefront
2. Order validation — System validates shipping address and payment method
3. Provider selection — System selects configured shipping provider based on destination or user preference
4. Payload preparation — Order data is transformed into shipment payload format
5. API call — Adapter sends payload to provider's API endpoint
6. Label generation — Provider generates tracking number and shipping label
7. Response processing — System stores tracking info and updates order status
8. Label delivery — Label URL is provided for download/printing
9. Pickup scheduling — Provider schedules courier pickup (if applicable)
10. Tracking activation — Shipment tracking becomes active in provider's system

Advanced integration patterns

Multiple providers

For stores shipping to multiple regions, you can implement provider selection logic:

// Select provider based on destination country
$provider = match ($shipmentData['recipient']['country']) {
    'EG' => 'bosta',
    'SA' => 'smsa',
    'AE' => 'fetchr',
    default => 'aramex'
};

$adapter = $adapterFactory->getAdapter($provider);

Batch shipments

For bulk order processing, you can create multiple shipments in a loop:

$orders = Order::where('status', 'pending')->get();

foreach ($orders as $order) {
    try {
        $adapter = $adapterFactory->getAdapter($order->shipping_provider);
        $shipmentData = prepareShipmentData($order);
        $response = $adapter->createShipment($shipmentData);
        
        $order->update([
            'tracking_number' => $response['tracking_number'],
            'status' => 'processing'
        ]);
    } catch (\Exception $e) {
        Log::error("Shipment failed for order {$order->id}: " . $e->getMessage());
    }
}

Automatic label generation

When a new order is created, the system can automatically generate shipping labels (AWB) if:

• A shipping provider is configured and active.
• The order has a valid shipping address.
• The order payment is confirmed (for COD orders, the COD amount is included).

1. Orders in Pending status are eligible for label generation.
2. The system sends shipment data to the configured provider's API.
3. The provider returns a tracking number and printable label.
4. The tracking number is saved to the order and displayed in the order details.
5. Order status updates to Processing when label is generated.

Cash on Delivery (COD) handling

COD orders require special handling for amount collection and currency rules:

• COD amount — The order total is sent to the provider as the COD amount to collect.
• Currency rules — Some providers only accept COD in specific currencies (e.g., EGP for Egypt providers).
• Currency conversion — If your store uses a different currency, the system converts the COD amount to the provider's accepted currency.
• COD fees — Some providers charge additional fees for COD orders. These are typically deducted from the collected amount.

Real-time shipment tracking

Track shipments and sync status changes from the provider to your order system:

1. Providers send webhook updates when shipment status changes.
2. Keddily receives these updates and syncs them to your order.
3. Order status updates automatically based on provider status.
4. Customers can track their orders using the tracking number on your storefront.

Manual label generation

If automatic label generation fails or you need to regenerate:

1. Open the order details from All Orders.
2. Click Generate Label in the shipping section.
3. Select the shipping provider if multiple are available.
4. The system requests a new label from the provider.
5. Download or print the label for package attachment.

Simulation adapter

The built-in Simulation Adapter lets you test store checkout and label generation without connecting to real carriers:

• Testing checkout — Simulate the complete order-to-shipping workflow.
• Label generation — Generates mock tracking numbers and labels.
• Status updates — Simulates shipment status changes over time.
• No costs — No actual shipping fees or API calls.

1. In Shipping Hub, find the Simulation provider.
2. Click Configure — minimal setup required (portal username/password).
3. Set optional parameters like Bot Delay (ms) and Success Rate (%).
4. Save and activate the simulation adapter.
5. Test your checkout flow — orders will use simulation for shipping.

Manual shipping adapter

For local couriers without API integration, use the Manual adapter:

• Contact-based — Configure phone and email for courier communication.
• Label templates — Choose from standard A4 or thermal printer formats.
• Pickup address — Set default pickup location for courier collection.
• Manual tracking — Update shipment status manually in the order system.

1. In Shipping Hub, find Local Courier Manual.
2. Configure contact details (phone, email) for the courier.
3. Select label template and set pickup address.
4. Save and activate the manual adapter.
5. When orders use this provider, you'll need to manually coordinate with the courier.

Switching between providers

You can configure multiple providers and switch between them:

1. Configure credentials for multiple providers in Shipping Hub.
2. Set each provider's Active toggle to enable/disable.
3. When creating orders, select which provider to use (if multiple are active).
4. Deactivate a provider to stop using it for new orders.
5. Existing orders continue to use their originally assigned provider.