README

Official PHP SDK for the Dolivroo Delivery API - Unified shipping API for Algeria.

Features

• ✅ Unified API - Single interface for Yalidine, Ecotrack, ZR Express
• ✅ Full CRUD - Create, track, update, cancel parcels
• ✅ Rate Comparison - Compare shipping rates across providers
• ✅ Bulk Operations - Mass parcel creation with progress tracking
• ✅ Label Generation - Download shipping labels as PDF
• ✅ Laravel Ready - Service provider, facade, and config publishing
• ✅ Fully Typed - PHP 8.1+ with strict types and IDE autocompletion

Requirements

• PHP 8.1 or higher
• Guzzle HTTP 7.0+

Installation

composer require dolivroo/sdk

Laravel Setup

The SDK automatically registers itself via Laravel package discovery.

Publish the config file:

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

Add your API key to .env:

DOLIVROO_API_KEY=your-api-key-here

Quick Start

Standalone Usage

use Dolivroo\Dolivroo;

$dolivroo = new Dolivroo('your-api-key');

// Create a parcel
$parcel = $dolivroo->parcels->create('yalidine', [
    'customer' => [
        'first_name' => 'Mohamed',
        'last_name' => 'Ali',
        'phone' => '0555000000',
        'address' => '123 Rue Test'
    ],
    'destination' => [
        'wilaya' => 'Alger',
        'commune' => 'Bab El Oued'
    ],
    'package' => [
        'products' => 'T-Shirt x2',
        'weight' => 1.5
    ],
    'payment' => [
        'amount' => 2500,
        'free_shipping' => false
    ],
    'options' => [
        'delivery_type' => 'home'
    ]
]);

echo $parcel['tracking_id']; // YAL123456

Laravel Usage

use Dolivroo\Laravel\Facades\Dolivroo;

// Using the facade
$parcel = Dolivroo::parcels->create('yalidine', [...]);

// Using dependency injection
public function ship(Dolivroo\Dolivroo $dolivroo)
{
    return $dolivroo->parcels->create('yalidine', [...]);
}

API Reference

Parcels

// Create a parcel
$dolivroo->parcels->create($companyCode, $order);

// Get parcel status
$dolivroo->parcels->get($companyCode, $trackingId);

// List all parcels
$dolivroo->parcels->list($companyCode, ['page' => 1]);

// Update a parcel
$dolivroo->parcels->update($companyCode, $trackingId, $order);

// Cancel a parcel
$dolivroo->parcels->cancel($companyCode, $trackingId);

// Get label (returns base64)
$dolivroo->parcels->label($companyCode, $trackingId);

// Download label as binary PDF
$pdf = $dolivroo->parcels->downloadLabel($companyCode, $trackingId);

// Save label to file
$dolivroo->parcels->saveLabel($companyCode, $trackingId, '/path/to/label.pdf');

Rates

// Get rates for a provider
$rates = $dolivroo->rates->get('Alger', 'Oran', 'yalidine');

// Compare all providers
$allRates = $dolivroo->rates->compare('Alger', 'Oran');

// Find cheapest option
$cheapest = $dolivroo->rates->findCheapest('Alger', 'Oran', 'home');

Bulk Operations

// Create bulk upload
$result = $dolivroo->bulk->create('yalidine', [
    [
        'recipient' => ['name' => 'Customer 1', 'phone' => '0555111111'],
        'destination' => ['wilaya_id' => 16, 'commune' => 'Bab El Oued'],
        'parcel' => ['products' => 'Item A', 'amount' => 2000]
    ],
    // ... more orders
], autoProcess: true);

// Check status
$status = $dolivroo->bulk->status($result['sheet_id']);

// Wait for completion (polls until done)
$final = $dolivroo->bulk->waitForCompletion($result['sheet_id']);

// Get detailed results
$results = $dolivroo->bulk->results($result['sheet_id']);

Wilayas

// List all wilayas
$wilayas = $dolivroo->wilayas->all();

// Find by name (fuzzy search)
$alger = $dolivroo->wilayas->find('Alger');

// Get by ID
$wilaya = $dolivroo->wilayas->get(16);

// Validate
if ($dolivroo->wilayas->isValid('Algr')) { // typo
    // false
}

Centers (StopDesk)

// Get centers in a wilaya
$centers = $dolivroo->centers->inWilaya(16, 'yalidine');

Error Handling

use Dolivroo\Exceptions\DolivrooException;
use Dolivroo\Exceptions\ValidationException;
use Dolivroo\Exceptions\AuthenticationException;
use Dolivroo\Exceptions\RateLimitException;
use Dolivroo\Exceptions\NotFoundException;

try {
    $parcel = $dolivroo->parcels->create('yalidine', $order);
} catch (ValidationException $e) {
    // Handle validation errors
    $errors = $e->getErrors();
    if ($e->hasFieldError('customer.phone')) {
        echo "Invalid phone: " . implode(', ', $e->getFieldErrors('customer.phone'));
    }
} catch (AuthenticationException $e) {
    // Invalid API key
    echo "Auth failed: " . $e->getMessage();
} catch (RateLimitException $e) {
    // Too many requests
    sleep(60);
    // Retry...
} catch (NotFoundException $e) {
    // Parcel not found
} catch (DolivrooException $e) {
    // General error
    echo "Error: " . $e->getMessage();
}

Configuration Options

$dolivroo = new Dolivroo('api-key', [
    'base_url' => 'https://custom-url.com/api/v1/unified',
    'timeout' => 60,       // Request timeout in seconds
    'verify_ssl' => false, // Disable SSL verification (dev only)
]);

Supported Providers

Testing

composer test

License

MIT License. See LICENSE for details.

Support

• 📧 Email: support@dolivroo.com
• 📖 Docs: https://dolivroo.com/dashboard/docs
• 🐛 Issues: https://github.com/dolivroo/sdk/issues