PHPackages                             mohamedhabibwork/laravel-tawseel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. mohamedhabibwork/laravel-tawseel

ActiveLibrary

mohamedhabibwork/laravel-tawseel
================================

This is my package laravel-tawseel

00[2 PRs](https://github.com/mohamedhabibwork/laravel-tawseel/pulls)PHPCI passing

Since Jan 13Pushed 1mo agoCompare

[ Source](https://github.com/mohamedhabibwork/laravel-tawseel)[ Packagist](https://packagist.org/packages/mohamedhabibwork/laravel-tawseel)[ RSS](/packages/mohamedhabibwork-laravel-tawseel/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (3)Used By (0)

Laravel Tawseel
===============

[](#laravel-tawseel)

[![Latest Version on Packagist](https://camo.githubusercontent.com/8a86fefa9de01d0eb49cc3fbee22049d08ed0b09ba18083272da3c5a56614f3a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6f68616d65646861626962776f726b2f6c61726176656c2d7461777365656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mohamedhabibwork/laravel-tawseel)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/0a6fd85a2b7915c3380e2f189477f6e76c01d1df8b479335d41509ad5d2f0de3/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6d6f68616d65646861626962776f726b2f6c61726176656c2d7461777365656c2f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/mohamedhabibwork/laravel-tawseel/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/195e810ddd02b32c31601483a47924d0cab4f28915a03bf816e0fd829152e714/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6f68616d65646861626962776f726b2f6c61726176656c2d7461777365656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mohamedhabibwork/laravel-tawseel)

A comprehensive Laravel package for integrating with the Tawseel Delivery API. This package provides a clean, type-safe interface for managing drivers, orders, contact information, and lookups in the Tawseel delivery system.

Features
--------

[](#features)

- ✅ **16 Complete API Endpoints** - Full coverage of Tawseel Delivery API
- ✅ **Type-Safe DTOs** - Request and Response Data Transfer Objects with strict typing
- ✅ **Comprehensive Error Handling** - Custom exceptions with error code mapping
- ✅ **Validation Rules** - Custom Laravel validation rules for Saudi-specific formats
- ✅ **PHP 8.3+ Support** - Modern PHP features (readonly properties, typed constants, etc.)
- ✅ **Laravel Integration** - Uses Laravel's HTTP client and validation
- ✅ **Facade Support** - Easy access via Laravel facade
- ✅ **Array Parsing** - Support for array responses (lookups)

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require mohamedhabibwork/laravel-tawseel
```

You can publish the config file with:

```
php artisan vendor:publish --tag="laravel-tawseel-config"
```

Configuration
-------------

[](#configuration)

After publishing the config file, update `config/tawseel.php` or set the following environment variables in your `.env` file:

```
TAWSEEL_ENVIRONMENT=test
TAWSEEL_COMPANY_NAME=your_company_name
TAWSEEL_PASSWORD=your_password
TAWSEEL_TEST_URL=https://demo-apitawseel.naql.sa
TAWSEEL_PRODUCTION_URL=https://tawseelapi.ecloud.sa
TAWSEEL_TIMEOUT=30
```

### Config File Structure

[](#config-file-structure)

```
return [
    'environment' => env('TAWSEEL_ENVIRONMENT', 'test'),

    'base_urls' => [
        'test' => env('TAWSEEL_TEST_URL', 'https://demo-apitawseel.naql.sa'),
        'production' => env('TAWSEEL_PRODUCTION_URL', 'https://tawseelapi.ecloud.sa'),
    ],

    'company_name' => env('TAWSEEL_COMPANY_NAME', ''),
    'password' => env('TAWSEEL_PASSWORD', ''),
    'timeout' => env('TAWSEEL_TIMEOUT', 30),
];
```

Usage
-----

[](#usage)

### Using the Facade

[](#using-the-facade)

```
use Habib\LaravelTawseel\Facades\LaravelTawseel;
use Habib\LaravelTawseel\DTOs\Requests\CredentialDTO;
use Habib\LaravelTawseel\DTOs\Requests\Driver\CreateDriverDTO;
```

### Driver Management

[](#driver-management)

#### Create Driver

[](#create-driver)

```
use Habib\LaravelTawseel\Facades\LaravelTawseel;
use Habib\LaravelTawseel\DTOs\Requests\CredentialDTO;
use Habib\LaravelTawseel\DTOs\Requests\Driver\CreateDriverDTO;

$credential = new CredentialDTO(
    companyName: config('tawseel.company_name'),
    password: config('tawseel.password')
);

$driverDTO = new CreateDriverDTO(
    credential: $credential,
    identityTypeId: 'NV25GlPuOnQ=',
    idNumber: '1016990911',
    dateOfBirth: 19900419,
    registrationDate: '2020-04-02T17:41:59.277Z',
    mobile: '0512547848',
    regionId: 'NV25GlPuOnQ=',
    carTypeId: 'oIcaYzeDfQQ=',
    cityId: 'NV25GlPuOnQ=',
    carNumber: '1234ABC',
    vehicleSequenceNumber: '123456789'
);

$driver = LaravelTawseel::createDriver($driverDTO);
echo $driver->refrenceCode; // Driver reference code
```

#### Get Driver

[](#get-driver)

```
use Habib\LaravelTawseel\Facades\LaravelTawseel;
use Habib\LaravelTawseel\DTOs\Requests\CredentialDTO;
use Habib\LaravelTawseel\DTOs\Requests\Driver\GetDriverDTO;

$credential = new CredentialDTO(
    companyName: config('tawseel.company_name'),
    password: config('tawseel.password')
);

$getDriverDTO = new GetDriverDTO(
    credential: $credential,
    idNumber: '1016990911'
);

$driver = LaravelTawseel::getDriver($getDriverDTO);
```

#### Edit Driver

[](#edit-driver)

```
use Habib\LaravelTawseel\Facades\LaravelTawseel;
use Habib\LaravelTawseel\DTOs\Requests\Driver\EditDriverDTO;

$editDriverDTO = new EditDriverDTO(
    credential: $credential,
    refrenceCode: '87834',
    identityTypeId: 'NV25GlPuOnQ=',
    idNumber: '1016990911',
    dateOfBirth: 19900419,
    registrationDate: '2020-04-02T17:41:59.277Z',
    mobile: '0555555555',
    regionId: 'NV25GlPuOnQ=',
    carTypeId: 'oIcaYzeDfQQ=',
    cityId: 'NV25GlPuOnQ=',
    carNumber: '1234ERS',
    vehicleSequenceNumber: '987564212'
);

$driver = LaravelTawseel::editDriver($editDriverDTO);
```

#### Deactivate Driver

[](#deactivate-driver)

```
use Habib\LaravelTawseel\Facades\LaravelTawseel;
use Habib\LaravelTawseel\DTOs\Requests\Driver\DeactivateDriverDTO;

$deactivateDTO = new DeactivateDriverDTO(
    credential: $credential,
    idNumber: '1016990911'
);

$driver = LaravelTawseel::deactivateDriver($deactivateDTO);
```

### Order Management

[](#order-management)

#### Create Order

[](#create-order)

```
use Habib\LaravelTawseel\Facades\LaravelTawseel;
use Habib\LaravelTawseel\DTOs\Requests\Order\CreateOrderDTO;

$createOrderDTO = new CreateOrderDTO(
    credential: $credential,
    orderNumber: 'ORD-20231201-001',
    authorityId: 'NV25GlPuOnQ=',
    deliveryTime: '2020-04-08T12:43:33.369Z',
    regionId: 'NV25GlPuOnQ=',
    cityId: 'NV25GlPuOnQ=',
    coordinates: '24.7842, 46.6453',
    storetName: 'Halol Restaurant',
    storeLocation: '24.751433, 46.740517',
    categoryId: 'NV25GlPuOnQ=',
    orderDate: '2020-04-19T12:07:10.723Z',
    recipientMobileNumber: '966555555555'
);

$order = LaravelTawseel::createOrder($createOrderDTO);
echo $order->referenceCode; // Order reference code
```

#### Accept Order

[](#accept-order)

```
use Habib\LaravelTawseel\Facades\LaravelTawseel;
use Habib\LaravelTawseel\DTOs\Requests\Order\AcceptOrderDTO;

$acceptOrderDTO = new AcceptOrderDTO(
    credential: $credential,
    referenceCode: '7kRgMtOkdQE=',
    acceptanceDateTime: '2020-04-08T15:43:29.228Z'
);

$accepted = LaravelTawseel::acceptOrder($acceptOrderDTO);
```

#### Assign Driver to Order

[](#assign-driver-to-order)

```
use Habib\LaravelTawseel\Facades\LaravelTawseel;
use Habib\LaravelTawseel\DTOs\Requests\Order\AssignDriverToOrderDTO;

$assignDTO = new AssignDriverToOrderDTO(
    credential: $credential,
    referenceCode: '7kRgMtOkdQE=',
    idNumber: '1016990911'
);

$assigned = LaravelTawseel::assignDriverToOrder($assignDTO);
```

#### Execute Order

[](#execute-order)

```
use Habib\LaravelTawseel\Facades\LaravelTawseel;
use Habib\LaravelTawseel\DTOs\Requests\Order\ExecuteOrderDTO;

$executeDTO = new ExecuteOrderDTO(
    credential: $credential,
    referenceCode: '7kRgMtOkdQE=',
    executionTime: '2020-04-08T15:49:19.459Z',
    paymentMethodId: 'NV25GlPuOnQ=',
    price: 180.5,
    priceWithoutDelivery: 150.0,
    deliveryPrice: 30.5,
    driverIncome: 20.0
);

$execution = LaravelTawseel::executeOrder($executeDTO);
```

#### Get Order

[](#get-order)

```
use Habib\LaravelTawseel\Facades\LaravelTawseel;
use Habib\LaravelTawseel\DTOs\Requests\Order\GetOrderDTO;

$getOrderDTO = new GetOrderDTO(
    credential: $credential,
    refrenceCode: '7kRgMtOkdQE='
);

$order = LaravelTawseel::getOrder($getOrderDTO);
echo $order->status; // Order status
```

### Contact Information

[](#contact-information)

#### Create/Update Contact Info

[](#createupdate-contact-info)

```
use Habib\LaravelTawseel\Facades\LaravelTawseel;
use Habib\LaravelTawseel\DTOs\Requests\ContactInfo\CreateContactInfoDTO;

$contactInfoDTO = new CreateContactInfoDTO(
    credential: $credential,
    responsibleName: 'Ahmed Al-Mansoori',
    responsibleEmail: 'ahmed@company.com',
    responsibleMobileNumber: '966555123456',
    technicalName: 'Sara Al-Otaibi',
    technicalEmail: 'sara@company.com',
    technicalMobileNumber: '966555654321'
);

$created = LaravelTawseel::createContactInfo($contactInfoDTO);
```

#### Get Contact Info

[](#get-contact-info)

```
use Habib\LaravelTawseel\Facades\LaravelTawseel;
use Habib\LaravelTawseel\DTOs\Requests\ContactInfo\GetContactInfoDTO;

$getContactDTO = new GetContactInfoDTO(
    companyName: config('tawseel.company_name'),
    password: config('tawseel.password')
);

$contactInfo = LaravelTawseel::getContactInfo($getContactDTO);
```

### Lookups

[](#lookups)

#### Get Lookups

[](#get-lookups)

```
use Habib\LaravelTawseel\Facades\LaravelTawseel;
use Habib\LaravelTawseel\Enums\LookupType;
use Habib\LaravelTawseel\DTOs\Requests\Lookup\GeneralLookupDTO;

$lookupDTO = new GeneralLookupDTO(
    companyName: config('tawseel.company_name'),
    password: config('tawseel.password')
);

// Get regions
$regions = LaravelTawseel::getLookup(LookupType::Regions, $lookupDTO);

// Get categories
$categories = LaravelTawseel::getLookup(LookupType::Categories, $lookupDTO);

// Get payment methods
$paymentMethods = LaravelTawseel::getLookup(LookupType::PaymentMethods, $lookupDTO);

// Available lookup types:
// - LookupType::Authorities
// - LookupType::CancellationReasons
// - LookupType::Regions
// - LookupType::Categories
// - LookupType::IdentityTypes
// - LookupType::PaymentMethods
// - LookupType::CarTypes
// - LookupType::Countries

foreach ($regions as $region) {
    echo $region->nameEn; // English name
    echo $region->nameAr; // Arabic name
    echo $region->id;    // Lookup ID
}
```

#### Get Cities by Region

[](#get-cities-by-region)

```
use Habib\LaravelTawseel\Facades\LaravelTawseel;
use Habib\LaravelTawseel\DTOs\Requests\Lookup\CitiesLookupDTO;

$citiesDTO = new CitiesLookupDTO(
    credential: $credential,
    regionId: 'NV25GlPuOnQ='
);

$cities = LaravelTawseel::getCities($citiesDTO);

foreach ($cities as $city) {
    echo $city->nameEn;
    echo $city->id;
}
```

Error Handling
--------------

[](#error-handling)

The package provides comprehensive error handling with custom exceptions:

```
use Habib\LaravelTawseel\Exceptions\TawseelApiException;
use Habib\LaravelTawseel\Exceptions\TawseelAuthenticationException;
use Habib\LaravelTawseel\Exceptions\TawseelValidationException;

try {
    $driver = LaravelTawseel::createDriver($driverDTO);
} catch (TawseelValidationException $e) {
    // Validation errors
    $errors = $e->getErrors();
} catch (TawseelAuthenticationException $e) {
    // Authentication failed
    echo $e->getMessage();
} catch (TawseelApiException $e) {
    // API error with error codes
    $errorCodes = $e->getErrorCodes();
    echo $e->getMessage();

    // Check for specific error code
    if ($e->hasErrorCode(47)) {
        echo 'Driver already exists';
    }
}
```

### Common Error Codes

[](#common-error-codes)

- `0` - Successful transaction
- `2` - Not found (Driver/Order)
- `5` - Invalid credentials
- `47` - Driver already exists
- `58` - Order number already exists today
- `72` - Can only assign driver to accepted orders
- `83` - COVID-19 active
- `94` - Not vaccinated against COVID-19

See the [API documentation](https://demo-apitawseel.naql.sa/) for the complete list of error codes.

Validation Rules
----------------

[](#validation-rules)

The package includes custom validation rules for Saudi-specific formats:

- `ValidIdNumber` - Validates Saudi ID (10 digits, starts with 1 or 2)
- `ValidMobileNumber` - Validates driver mobile (10 digits, starts with 05)
- `ValidRecipientMobile` - Validates recipient mobile (12 chars, starts with 9665)
- `ValidCarNumber` - Validates car number (4 digits + 3 letters)
- `ValidCoordinates` - Validates coordinates format ("latitude, longitude")
- `ValidDateOfBirth` - Validates date of birth (YYYYMMDD, 8 digits)

You can use these rules in your Laravel validation:

```
use Habib\LaravelTawseel\Rules\ValidIdNumber;
use Habib\LaravelTawseel\Rules\ValidMobileNumber;

$request->validate([
    'id_number' => ['required', new ValidIdNumber()],
    'mobile' => ['required', new ValidMobileNumber()],
]);
```

Available Methods
-----------------

[](#available-methods)

### Driver Management

[](#driver-management-1)

- `createDriver(CreateDriverDTO $dto): DriverResponseDTO`
- `editDriver(EditDriverDTO $dto): DriverResponseDTO`
- `getDriver(GetDriverDTO $dto): DriverResponseDTO`
- `deactivateDriver(DeactivateDriverDTO $dto): DriverResponseDTO`

### Order Management

[](#order-management-1)

- `createOrder(CreateOrderDTO $dto): OrderResponseDTO`
- `acceptOrder(AcceptOrderDTO $dto): bool`
- `rejectOrder(RejectOrderDTO $dto): bool`
- `assignDriverToOrder(AssignDriverToOrderDTO $dto): bool`
- `editOrderDeliveryAddress(EditOrderDeliveryAddressDTO $dto): bool`
- `executeOrder(ExecuteOrderDTO $dto): OrderExecutionResponseDTO`
- `cancelOrder(CancelOrderDTO $dto): bool`
- `getOrder(GetOrderDTO $dto): OrderResponseDTO`

### Contact Information

[](#contact-information-1)

- `createContactInfo(CreateContactInfoDTO $dto): bool`
- `getContactInfo(GetContactInfoDTO $dto): ContactInfoResponseDTO`

### Lookups

[](#lookups-1)

- `getLookup(LookupType $type, GeneralLookupDTO $dto): array`
- `getCities(CitiesLookupDTO $dto): array`

Testing
-------

[](#testing)

```
composer test
```

Requirements
------------

[](#requirements)

- PHP 8.3+
- Laravel 11.0+ or 12.0+

Support
-------

[](#support)

For API support, contact:

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Mohamed Habib](https://github.com/mohamedhabibwork)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

21

—

LowBetter than 19% of packages

Maintenance60

Regular maintenance activity

Popularity0

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity15

Early-stage or recently created project

 Bus Factor1

Top contributor holds 60% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/465ce474e9c105751d2df13e0aa0f243cdd37909529b7f957cac01251644b1b1?d=identicon)[mohamedhabibwork](/maintainers/mohamedhabibwork)

---

Top Contributors

[![mohamedhabibwork](https://avatars.githubusercontent.com/u/64292519?v=4)](https://github.com/mohamedhabibwork "mohamedhabibwork (3 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)")

### Embed Badge

![Health badge](/badges/mohamedhabibwork-laravel-tawseel/health.svg)

```
[![Health](https://phpackages.com/badges/mohamedhabibwork-laravel-tawseel/health.svg)](https://phpackages.com/packages/mohamedhabibwork-laravel-tawseel)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)