PHPackages                             ht3aa/zaeem-delivery - 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. [API Development](/categories/api)
4. /
5. ht3aa/zaeem-delivery

ActiveLibrary[API Development](/categories/api)

ht3aa/zaeem-delivery
====================

Zaeem Delivery integration for laravel. You will find all the functionality you need to make it a shipment with zaeem delivery logistics

v0.0.4(4mo ago)21[1 PRs](https://github.com/ht3aa/zaeem-delivery/pulls)MITPHPPHP ^8.4CI passing

Since Jan 3Pushed 1mo agoCompare

[ Source](https://github.com/ht3aa/zaeem-delivery)[ Packagist](https://packagist.org/packages/ht3aa/zaeem-delivery)[ Docs](https://github.com/ht3aa/zaeem-delivery)[ GitHub Sponsors](https://github.com/ht3aa)[ RSS](/packages/ht3aa-zaeem-delivery/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (13)Versions (9)Used By (0)

Zaeem Delivery integration for laravel.
=======================================

[](#zaeem-delivery-integration-for-laravel)

[![Latest Version on Packagist](https://camo.githubusercontent.com/e397b3ef26d4ed9d85bce358b0e122214413b59a28457b27b07087ef5065d307/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f68743361612f7a6165656d2d64656c69766572792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ht3aa/zaeem-delivery)[![Total Downloads](https://camo.githubusercontent.com/f2c22d677511cbb2bcb672682ee7aca19325ebc5e1578efaa9e00ec6fb1335d1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f68743361612f7a6165656d2d64656c69766572792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ht3aa/zaeem-delivery)

[![Zaeem Delivery Integration For Laravel](image.png)](image.png)

Zaeem Delivery integration for Laravel. You will find all the functionality you need to make shipments with Zaeem Delivery logistics, including store management, shipment creation, real-time webhook integration for status updates, and reference data synchronization. [Zaeem Delivery API](https://jenni.alzaeemexp.com/api/v2/docs)

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

[](#installation)

You can install the package via composer:

```
composer require ht3aa/zaeem-delivery
```

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

[](#configuration)

Publish the configuration file:

```
php artisan vendor:publish --tag="zaeem-delivery-config"
```

Add the following environment variables to your `.env` file:

```
ZAEEM_DELIVERY_USERNAME=your_username
ZAEEM_DELIVERY_PASSWORD=your_password
ZAEEM_DELIVERY_SYSTEM_CODE=your_system_code
```

Database Migrations
-------------------

[](#database-migrations)

Publish the migrations:

```
php artisan vendor:publish --tag="zaeem-delivery-migrations"
```

Then run the migrations to create the necessary tables:

```
php artisan migrate
```

This will create the following tables:

- `zaeem_governorates` - Stores governorate reference data
- `zaeem_cities` - Stores city reference data
- `zaeem_stores` - Stores your Zaeem Delivery store information
- `zaeem_shipments` - Stores shipment information
- `zaeem_shipment_updates` - Stores shipment status updates received from webhooks

Usage
-----

[](#usage)

### Authentication

[](#authentication)

Before making API calls, you need to authenticate:

```
use Ht3aa\ZaeemDelivery\Facades\ZaeemDelivery;

ZaeemDelivery::login();
```

### Creating a Store

[](#creating-a-store)

Create a new store in Zaeem Delivery:

```
use Ht3aa\ZaeemDelivery\Facades\ZaeemDelivery;
use Ht3aa\ZaeemDelivery\Models\ZaeemStore;

// make zaeem store object
$store = ZaeemStore::make([
    'store_name' => 'My Store',
    'store_phone' => '1234567890',
    'governorate_code' => 'GOV001',
    'address' => '123 Main Street',
    'latitude' => 31.2001,
    'longitude' => 29.9187,
    'owner_id' => auth()->id(),
    'owner_type' => auth()->user()->getMorphClass(),
]);

// create store in zaeem
$createdStore = ZaeemDelivery::createStore($store);

// save the store in the database
$createdStore->save();
```

### Creating a Shipment

[](#creating-a-shipment)

Create a new shipment:

```
use Ht3aa\ZaeemDelivery\Facades\ZaeemDelivery;
use Ht3aa\ZaeemDelivery\Models\ZaeemShipment;

$shipment = new ZaeemShipment([
    // Add your shipment data here
    // make sure to include all the needed fields and especilly the store_id field (even if it nullabel)
    // it required to identifiy the store
]);

$createdShipment = ZaeemDelivery::createShipment($shipment);

$createdShipment->save();
```

### Webhook Integration

[](#webhook-integration)

The package provides a webhook endpoint to receive shipment status updates from Zaeem Delivery.

#### Configure Webhook URL

[](#configure-webhook-url)

In your Zaeem Delivery dashboard, configure the webhook URL to:

```
https://yourdomain.com/api/zaeem-delivery/v2/push/update-status

```

The webhook endpoint will automatically:

- Validate the incoming system code
- Store all shipment updates in the `zaeem_shipment_updates` table
- Update the shipment status if a matching shipment is found

#### Webhook Payload

[](#webhook-payload)

Zaeem Delivery will send POST requests with the following structure:

```
{
  "system_code": "your_system_code",
  "updates": [
    {
      "shipment_number": "SH123456",
      "external_id": "ORDER-001",
      "action_code": "DELIVERED",
      "current_step": "Delivered",
      "current_step_ar": "تم التسليم",
      "current_stage": "final",
      "current_stage_ar": "نهائي",
      "governorate_code": "GOV001",
      "governorate_name": "Baghdad",
      "note": "Delivered successfully",
      "agent_latitude": 33.3152,
      "agent_longitude": 44.3661,
      "amount_iqd": 25000,
      "amount_usd": 0,
      "quantity_delivered": 1,
      "quantity_returned": 0
    }
  ]
}
```

#### Accessing Shipment Updates

[](#accessing-shipment-updates)

You can access shipment updates through the `ZaeemShipmentUpdate` model:

```
use Ht3aa\ZaeemDelivery\Models\ZaeemShipment;
use Ht3aa\ZaeemDelivery\Models\ZaeemShipmentUpdate;

// Get all updates for a specific shipment
$shipment = ZaeemShipment::where('shipment_number', 'SH123456')->first();
$updates = ZaeemShipmentUpdate::where('zaeem_shipment_id', $shipment->id)->get();

// Get the latest update
$latestUpdate = ZaeemShipmentUpdate::where('zaeem_shipment_id', $shipment->id)
    ->latest()
    ->first();

// Access update data
echo $latestUpdate->updates['current_step'];
echo $latestUpdate->updates['note'];
```

### Fetching Reference Data

[](#fetching-reference-data)

#### Fetch Governorates

[](#fetch-governorates)

Sync governorates from the Zaeem Delivery API:

```
php artisan zaeem:fetch-governorates
```

This command will fetch all governorates and store them in the `zaeem_governorates` table.

#### Fetch Cities

[](#fetch-cities)

Sync cities from the Zaeem Delivery API:

```
php artisan zaeem:fetch-cities
```

If the command fails at some point, you can resume from a specific page:

```
php artisan zaeem:fetch-cities --start=5
```

### Using Models

[](#using-models)

#### ZaeemGovernorate Model

[](#zaeemgovernorate-model)

```
use Ht3aa\ZaeemDelivery\Models\ZaeemGovernorate;

// Get all governorates
$governorates = ZaeemGovernorate::all();

// Find by code
$governorate = ZaeemGovernorate::where('code', 'GOV001')->first();
```

#### ZaeemCity Model

[](#zaeemcity-model)

```
use Ht3aa\ZaeemDelivery\Models\ZaeemCity;

// Get all cities
$cities = ZaeemCity::all();

// Find by city ID
$city = ZaeemCity::where('city_id', 123)->first();

// Get cities by governorate
$cities = ZaeemCity::where('governorate_code', 'GOV001')->get();
```

#### ZaeemShipment Model

[](#zaeemshipment-model)

```
use Ht3aa\ZaeemDelivery\Models\ZaeemShipment;

// Get all shipments
$shipments = ZaeemShipment::all();

// Find by shipment number
$shipment = ZaeemShipment::where('shipment_number', 'SH123456')->first();

// Find by external shipment ID
$shipment = ZaeemShipment::where('external_shipment_id', 'ORDER-001')->first();

// Get shipment with relationships
$shipment = ZaeemShipment::with(['store', 'governorate'])->find(1);

// Check shipment status
echo $shipment->status;
```

#### ZaeemShipmentUpdate Model

[](#zaeemshipmentupdate-model)

```
use Ht3aa\ZaeemDelivery\Models\ZaeemShipmentUpdate;

// Get all updates for a shipment
$updates = ZaeemShipmentUpdate::where('zaeem_shipment_id', 1)->get();

// Get latest updates
$latestUpdates = ZaeemShipmentUpdate::latest()->take(10)->get();

// Access update data
foreach ($updates as $update) {
    echo $update->updates['current_step'];
    echo $update->updates['note'];
    echo $update->created_at;
}
```

Available Commands
------------------

[](#available-commands)

- `zaeem:fetch-governorates` - Fetch and sync governorates from Zaeem Delivery API
- `zaeem:fetch-cities` - Fetch and sync cities from Zaeem Delivery API (supports `--start` option to resume from a specific page)

Features
--------

[](#features)

- ✅ Authentication with Zaeem Delivery API
- ✅ Store creation and management
- ✅ Shipment creation and tracking
- ✅ Webhook integration for real-time shipment status updates
- ✅ Governorate and city reference data synchronization
- ✅ Eloquent models for shipments, updates, governorates, cities, and stores
- ✅ Repository pattern for processing webhook updates
- ✅ Automatic shipment status updates via webhooks
- ✅ Database migrations included
- ✅ Artisan commands for data synchronization
- ✅ Configurable API endpoints and credentials
- ✅ Transaction support for reliable data processing

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

[](#requirements)

- PHP ^8.4
- Laravel ^11.0 or ^12.0

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)

- [Hasan Tahseen](https://github.com/ht3aa)
- [All Contributors](../../contributors)

License
-------

[](#license)

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

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance84

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 93% 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.

###  Release Activity

Cadence

Every ~1 days

Total

4

Last Release

124d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/5960d0e04603296e1d859501a366241098d1a46c95f0bfc47f0541871b08cfbb?d=identicon)[ht3aa](/maintainers/ht3aa)

---

Top Contributors

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

---

Tags

laravelht3aazaeem-delivery

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/ht3aa-zaeem-delivery/health.svg)

```
[![Health](https://phpackages.com/badges/ht3aa-zaeem-delivery/health.svg)](https://phpackages.com/packages/ht3aa-zaeem-delivery)
```

###  Alternatives

[dedoc/scramble

Automatic generation of API documentation for Laravel applications.

2.0k7.8M55](/packages/dedoc-scramble)[scalar/laravel

Render your OpenAPI-based API reference

6183.9k2](/packages/scalar-laravel)[ryangjchandler/bearer

Minimalistic token-based authentication for Laravel API endpoints.

8129.8k](/packages/ryangjchandler-bearer)[combindma/laravel-facebook-pixel

Meta pixel integration for Laravel

4956.9k](/packages/combindma-laravel-facebook-pixel)[stechstudio/laravel-hubspot

A Laravel SDK for the HubSpot CRM Api

2971.0k](/packages/stechstudio-laravel-hubspot)[likeabas/filament-chatgpt-agent

Integrate with OpenAI ChatGPT

235.3k](/packages/likeabas-filament-chatgpt-agent)

PHPackages © 2026

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