واجهة التاجر في Delivery Syria

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X GET "https://YOUR_DOMAIN/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/me");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
    ],
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/me", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
  },
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.get(
    "https://YOUR_DOMAIN/api/v1/me",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

قوائم الاختيار

قوائم مرجعية تحتاجها قبل إنشاء الطرد: شركات التوصيل والشحن والمحافظات وأماكن الاستلام ومخزون المستودعات.

الطريقة GET `/companies` #

قائمة شركات التوصيل والشحن

تعرض شركات التوصيل وشركات الشحن التي يمكنك استخدامها. أرسل قيمة id على أنها company_id عند التسعير أو إنشاء الطرد. القائمة غير مرقّمة.

الطلب GET /api/v1/companies
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة مرجع واجهة التاجر API v1

الردود

200 الشركات التي يمكنك استخدامها.

الشركات التي يمكنك استخدامها.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`array<object>`	مطلوب
`id`	`integer`	مطلوب	أرسله على أنه `company_id`.
`name`	`string`	مطلوب	اسم الشركة.
`type`	`string`	مطلوب	`delivery_company` أو `carrier` (شركة شحن خارجية). إحدى القيم: `delivery_company` `carrier`
`pricing_mode`	`string`	مطلوب	طريقة احتساب السعر: `governorate` (مبلغ ثابت حسب المحافظة) أو `per_kg` أو `per_km` أو `km_kg` أو `carrier_quote` (سعر شركة الشحن نفسها). تظهر `per_km` لشركة توصيل لا تحمل آلية محفوظة. إحدى القيم: `governorate` `per_kg` `per_km` `km_kg` `carrier_quote`
`supports_own_account`	`boolean`	مطلوب	تكون true عندما تسمح شركة الشحن بحسابات التجّار وتكون قد ربطتَ حسابك بها.
`coverage`	`object` \| null	مطلوب	`null` عندما لا تقيّد الشركة التغطية؛ وإلا فرمز الدولة ثم قائمة أسماء المحافظات التي تغطيها (`[]` تعني كل محافظات الدولة).

مثال

JSON · 200

{
  "success": true,
  "data": [
    {
      "id": 3,
      "name": "Example Delivery",
      "type": "delivery_company",
      "pricing_mode": "governorate",
      "supports_own_account": false,
      "coverage": null
    },
    {
      "id": 5,
      "name": "Example Carrier",
      "type": "carrier",
      "pricing_mode": "carrier_quote",
      "supports_own_account": true,
      "coverage": {
        "SY": []
      }
    }
  ]
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X GET "https://YOUR_DOMAIN/api/v1/companies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/companies");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
    ],
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/companies", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
  },
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.get(
    "https://YOUR_DOMAIN/api/v1/companies",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

الطريقة GET `/governorates` #

قائمة المحافظات

تُرجع id وname وname_ar لكل محافظة فعّالة. أرسل name أو name_ar في recipient.governorate. القائمة غير مرقّمة.

الطلب GET /api/v1/governorates
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة مرجع واجهة التاجر API v1

الردود

200 المحافظات الفعّالة.

المحافظات الفعّالة.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`array<object>`	مطلوب
`id`	`integer`	مطلوب	معرّف المحافظة. عند إرساله في `recipient.governorate` أرسله نصاً.
`name`	`string`	مطلوب	الاسم بالإنجليزية.
`name_ar`	`string`	مطلوب	الاسم بالعربية.

مثال

JSON · 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Damascus",
      "name_ar": "دمشق"
    }
  ]
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X GET "https://YOUR_DOMAIN/api/v1/governorates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/governorates");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
    ],
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/governorates", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
  },
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.get(
    "https://YOUR_DOMAIN/api/v1/governorates",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

الطريقة GET `/pickup-locations` #

قائمة أماكن الاستلام لديك

تُرجع أماكن الاستلام لديك والافتراضي أولاً. عند عدم إرسال pickup_location_id مع الطرد يُستخدم المكان الافتراضي. أضف الأماكن من لوحة التاجر. القائمة غير مرقّمة.

الطلب GET /api/v1/pickup-locations
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة مرجع واجهة التاجر API v1

الردود

200 أماكن الاستلام لديك.

أماكن الاستلام لديك.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`array<object>`	مطلوب
`id`	`integer`	مطلوب	أرسله على أنه `pickup_location_id`.
`name`	`string` \| null	مطلوب	اسم المكان.
`phone`	`string` \| null	مطلوب	هاتف التواصل.
`address`	`string` \| null	مطلوب	العنوان.
`lat`	`number` \| null	مطلوب	خط العرض.
`lng`	`number` \| null	مطلوب	خط الطول.
`default`	`boolean`	مطلوب	تكون true للمكان الافتراضي (يُستخدم عند عدم إرسال `pickup_location_id`).
`warehouse_id`	`integer` \| null	مطلوب	معرّف المستودع عندما يكون المكان مستودعاً، وإلا null.
`active`	`boolean`	مطلوب	هل يمكن استخدام المكان.

مثال

JSON · 200

{
  "success": true,
  "data": [
    {
      "id": 7,
      "name": "Main branch",
      "phone": "0900000000",
      "address": "Example street, building 1",
      "lat": null,
      "lng": null,
      "default": true,
      "warehouse_id": null,
      "active": true
    }
  ]
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X GET "https://YOUR_DOMAIN/api/v1/pickup-locations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/pickup-locations");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
    ],
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/pickup-locations", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
  },
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.get(
    "https://YOUR_DOMAIN/api/v1/pickup-locations",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

الطريقة GET `/warehouse/stock` #

جلب بضاعتك في المستودعات

لكل حجز مستودع فعّال: المستودع ومعرّف مكان الاستلام الخاص به (استخدمه على أنه pickup_location_id للشحن من هذا المخزون) والمنصّات والأصناف بكمياتها. تُرجع قائمة فارغة عند عدم وجود حجز فعّال.

الطلب GET /api/v1/warehouse/stock
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة مرجع واجهة التاجر API v1

الردود

200 المخزون لكل حجز مستودع.

المخزون لكل حجز مستودع.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`array<object>`	مطلوب
`warehouse_id`	`integer`	مطلوب	معرّف المستودع.
`warehouse`	`string` \| null	مطلوب	اسم المستودع.
`pickup_location_id`	`integer`	مطلوب	مكان الاستلام لهذا الحجز: استخدمه على أنه `pickup_location_id` للشحن من هذا المخزون.
`pallets`	`integer`	مطلوب	عدد المنصّات المحجوزة.
`items`	`array<object>`	مطلوب	أصناف المخزون.
`item_id`	`integer`	مطلوب	معرّف صنف المخزون.
`sku`	`string` \| null	مطلوب	رمز المنتج.
`name`	`string` \| null	مطلوب	اسم المنتج.
`qty`	`integer`	مطلوب	الكمية في المخزون.
`reserved`	`integer`	مطلوب	الكمية المحجوزة لطرود أخرى.
`available`	`integer`	مطلوب	الكمية التي ما زال بإمكانك شحنها.

مثال

JSON · 200

{
  "success": true,
  "data": [
    {
      "warehouse_id": 1,
      "warehouse": "Example Warehouse",
      "pickup_location_id": 9,
      "pallets": 2,
      "items": [
        {
          "item_id": 5,
          "sku": "A1",
          "name": "Example item",
          "qty": 20,
          "reserved": 2,
          "available": 18
        }
      ]
    }
  ]
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X GET "https://YOUR_DOMAIN/api/v1/warehouse/stock" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/warehouse/stock");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
    ],
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/warehouse/stock", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
  },
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.get(
    "https://YOUR_DOMAIN/api/v1/warehouse/stock",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

التسعير

احتساب سعر الطرد دون إنشائه.

الطريقة POST `/quote` #

تسعير طرد دون إنشائه

تحسب سعر الطرد على الخادم دون إنشائه ودون خصم أي مبلغ. تأخذ الحقول نفسها المستخدمة في POST /parcels والمطلوب فقط company_id، لكن الحقول التي يحتاجها السعر تعتمد على pricing_mode للشركة (انظر GET /companies): governorate يحتاج recipient.governorate (أو عنواناً تستطيع المنصة ربطه بمحافظة، أو إحداثيات)؛ وper_kg يحتاج weight؛ وper_km يحتاج recipient.lat وrecipient.lng ومكان استلام له موقع على الخريطة؛ وkm_kg يحتاج الاثنين؛ وcarrier_quote يطلب السعر من شركة الشحن. وفي التسعير الداخلي يُقرَّب الوزن إلى كيلوغرام كامل ويُطبَّق الحد الأدنى للأجرة عند الشركة. ويختلف الرد بين شركة التوصيل وشركة الشحن (انظر Quote).

الطلب POST /api/v1/quote
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة مرجع واجهة التاجر API v1

جسم الطلب

application/json · مطلوب

الحقل	النوع	مطلوب	الوصف
`company_id`	`integer`	مطلوب	شركة التوصيل أو الشحن، قيمة `id` من `GET /companies`. يجب أن تكون متاحة لحسابك.
`recipient`	`object`	اختياري	المستلم. يمكن بدلاً من ذلك إرسال كل حقل مسطحاً في المستوى الأعلى (`customer_name` و`customer_phone` و`customer_address` و`customer_city` و`lat` و`long`)؛ والشكل المتداخل هو الموثَّق.
`name`	`string`	اختياري	اسم المستلم. الحد الأقصى للطول 191
`phone`	`string`	اختياري	رقم هاتف المستلم: أرقام ومسافات و`+` و`-` وأقواس، من 6 إلى 30 محرفاً. الحد الأقصى للطول 30النمط `^[+0-9\s\-()]{6,30}$`
`address`	`string`	اختياري	عنوان المستلم. الحد الأقصى للطول 1000
`governorate`	`string`	اختياري	اسم المحافظة (`name` بالإنجليزية أو `name_ar` بالعربية من `GET /governorates`). وإن أرسلت المعرّف فأرسله نصاً مثل `"3"` لأن الرقم في JSON يُرفض. مطلوب للتسعير حسب المحافظة، وإلا تحاول المنصة استنتاجها من العنوان ثم من الإحداثيات. الحد الأقصى للطول 120يُقبل أيضاً باسم `customer_city, city`
`lat`	`number`	اختياري	خط عرض موقع المستلم. مطلوب للتسعير حسب المسافة (`per_km` و`km_kg`). الحد الأدنى -90الحد الأقصى 90
`lng`	`number`	اختياري	خط طول موقع المستلم. مطلوب للتسعير حسب المسافة (`per_km` و`km_kg`). الحد الأدنى -180الحد الأقصى 180يُقبل أيضاً باسم `long`
`reference`	`string`	اختياري	مرجعك الخاص (رقم الطلب). لا يؤثر في السعر. الحد الأقصى للطول 191يُقبل أيضاً باسم `invoice_no`
`cod_amount`	`number`	اختياري	مبلغ التحصيل عند الاستلام الذي يدفعه المستلم، من 0 إلى 100,000,000 دولار أمريكي (يُحوَّل المبلغ بغير الدولار إلى الدولار بسعر المنصة قبل فحص الحد). القيمة 0 تعني مدفوع مسبقاً. الحد الأدنى 0الحد الأقصى 100000000الافتراضي `0`
`currency`	`string`	اختياري	رمز عملة `cod_amount` (لا فرق بين الأحرف الكبيرة والصغيرة). يُخزَّن المبلغ بالدولار، لذا يكون `cod_amount` في كائنات الطرد بالدولار دائماً. وقد لا تقبل الشركة إلا بعض العملات. وغياب سعر الصرف يعطي `422`. إحدى القيم: `USD` `SYP` `SAR` `AED` `QAR` `KWD` `JOD` `IQD` `EGP` `LBP` `TRY` `EUR` الافتراضي `USD`يُقبل أيضاً باسم `cod_currency`
`weight`	`number`	اختياري	الوزن بالكيلوغرام من 0.01 إلى 1000. الافتراضي 1. في التسعير الداخلي يُقرَّب الوزن إلى كيلوغرام كامل (الحد الأدنى 1). الحد الأدنى 0.01الحد الأقصى 1000الافتراضي `1`يُقبل أيضاً باسم `weight_kg`
`pickup_location_id`	`integer`	اختياري	أحد أماكن الاستلام لديك (`GET /pickup-locations`). يُستخدم مكانك الافتراضي عند عدم الإرسال. وتُبلَّغ الأخطاء على الحقل `shop_id`. يُقبل أيضاً باسم `shop_id`
`note`	`string`	اختياري	ملاحظة لشركة التوصيل بحد أقصى 2000 محرف. الحد الأقصى للطول 2000
`use_own_account`	`boolean`	اختياري	الشحن بحسابك الخاص لدى شركة شحن تسمح بحسابات التجّار. يفشل بالرمز `carrier_error` إن كانت الشركة تسمح بها ولم تربط حسابك، ويُتجاهل إن كانت لا تسمح بها، ولا أثر له على شركات التوصيل.
`shipping_paid_by`	`string`	اختياري	من يدفع أجرة الشحن، لشركات الشحن التي تدعم الاختيار: `sender` (المرسل) أو `customer` (المستلم) أو `included_in_cod` (ضمن مبلغ التحصيل). إحدى القيم: `sender` `customer` `included_in_cod`

مثال

JSON

{
  "company_id": 3,
  "recipient": {
    "governorate": "Damascus"
  },
  "weight": 2
}

الردود

200 التسعيرة.

التسعيرة.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`oneOf`	مطلوب	يعتمد الشكل على الشركة: شركة التوصيل تعطي `QuoteDeliveryCompany` وشركة الشحن تعطي `QuoteCarrier` (ميّز بينهما بـ `pricing_mode`).
بديل `QuoteDeliveryCompany` تسعيرة لشركة توصيل.
`pricing_mode`	`string`	مطلوب	آلية التسعير المستخدمة. إحدى القيم: `governorate` `per_kg` `per_km` `km_kg`
`pricing_label`	`string` \| null	مطلوب	تسمية آلية التسعير بلغة الطلب.
`governorate`	`string` \| null	مطلوب	المحافظة المستخدمة في التسعير حسب المحافظة، وإلا null.
`distance_km`	`number`	مطلوب	المسافة المستخدمة (0 ما لم تعتمد الآلية على المسافة).
`weight_kg`	`number`	مطلوب	الوزن المستخدم مقرَّباً إلى كيلوغرام كامل (الحد الأدنى 1).
`delivery_fee`	`number`	مطلوب	أجرة التوصيل بالدولار.
`platform_fee`	`number`	مطلوب	رسم المنصة بالدولار.
`charged_now`	`number`	مطلوب	المبلغ الذي يُخصم من محفظتك عند الإنشاء: أجرة التوصيل مع رسم المنصة، أو رسم المنصة فقط لشركة التوصيل الداخلية الخاصة بك.
بديل `QuoteCarrier` تسعيرة لشركة شحن خارجية: كائن مختلف وأصغر. لا يتضمن `pricing_label` ولا `governorate` ولا `distance_km` ولا `weight_kg` ولا `delivery_fee`.
`pricing_mode`	`string`	مطلوب	قيمة ثابتة `"carrier_quote"`
`carrier`	`string`	مطلوب	اسم شركة الشحن.
`account`	`string`	مطلوب	الحساب الذي سيُستخدم: حساب المنصة أو حسابك الخاص لدى الشركة. إحدى القيم: `platform_account` `merchant_account`
`carrier_fee`	`number`	مطلوب	سعر شركة الشحن بعملتها.
`carrier_currency`	`string`	مطلوب	عملة `carrier_fee`.
`carrier_fee_usd`	`number`	مطلوب	سعر شركة الشحن بالدولار.
`platform_fee`	`number`	مطلوب	رسم المنصة بالدولار.
`charged_now`	`number`	مطلوب	المبلغ المخصوم من محفظتك عند الإنشاء بالدولار.
`held_now`	`number`	مطلوب	المبلغ المحجوز حتى التسليم (حسابك الخاص لدى الشركة) بالدولار.
`required_balance`	`number`	مطلوب	الرصيد الذي يجب أن يتوفر في محفظتك بالدولار.
`shipping_paid_by`	`string`	مطلوب	من يدفع أجرة الشحن (`sender` أو `customer` أو `included_in_cod`).
`receiver_pays`	`number`	مطلوب	المبلغ الذي يدفعه المستلم عند التسليم بالدولار.
`net_after_delivery`	`number`	مطلوب	صافي مبلغك بعد التسليم بالدولار.
`destination`	`string` \| null	مطلوب	ملاحظة الوجهة من شركة الشحن.
`currency`	`string`	مطلوب	قيمة ثابتة `"USD"`

مثال

JSON · 200

{
  "success": true,
  "data": {
    "pricing_mode": "governorate",
    "pricing_label": "Fixed amount per governorate",
    "governorate": "Damascus",
    "distance_km": 0,
    "weight_kg": 2,
    "delivery_fee": 6,
    "platform_fee": 1,
    "charged_now": 7
  }
}

422 validation_failed:

validation_failed: company_id مفقود أو غير متاح لك، أو ينقص حقل يحتاجه التسعير. quote_failed: تعذّر حساب السعر. carrier_error: رفضت شركة الشحن التسعير أو تعذّر عليها.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

مثال — Missing company

JSON · 422

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "company_id is required — get the list from GET /companies",
    "fields": {
      "company_id": [
        "company_id is required — get the list from GET /companies"
      ]
    }
  }
}

مثال — Price not calculated

JSON · 422

{
  "success": false,
  "error": {
    "code": "quote_failed",
    "message": "Could not calculate the price."
  }
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X POST "https://YOUR_DOMAIN/api/v1/quote" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "company_id": 3,
  "recipient": {
    "governorate": "Damascus"
  },
  "weight": 2
}'

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/quote");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'company_id' => 3,
        'recipient' => [
            'governorate' => 'Damascus',
        ],
        'weight' => 2,
    ]),
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/quote", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "company_id": 3,
    "recipient": {
      "governorate": "Damascus"
    },
    "weight": 2
  }),
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.post(
    "https://YOUR_DOMAIN/api/v1/quote",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    json={
        "company_id": 3,
        "recipient": {
            "governorate": "Damascus",
        },
        "weight": 2,
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

الطرود

إنشاء الطرود وعرضها وتتبّعها وإلغاؤها.

الطريقة GET `/parcels` #

عرض طرودك

تعرض طرودك الأحدث أولاً (حسب المعرّف) دون events. الطرود في المرحلة awaiting_funds لا تُعرض (اجلب الواحد منها برقم التتبع أو المرجع). الرد مرقّم ويتضمن meta.

الطلب GET /api/v1/parcels
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة مرجع واجهة التاجر API v1 الصفحات والفلاتر في الـ API

معاملات الاستعلام

الاسم	النوع	مطلوب	الوصف
`reference`	`string`	اختياري	تطابق تام مع `reference` الذي أرسلته عند الإنشاء. مثال `ORDER-1043`
`from`	`string (date)`	اختياري	أول يوم إنشاء `YYYY-MM-DD` شاملاً (بتوقيت UTC). لا يُتحقق من الصيغة: استخدم هذه الصيغة فقط. مثال `2026-01-01`
`to`	`string (date)`	اختياري	آخر يوم إنشاء `YYYY-MM-DD` شاملاً (بتوقيت UTC). لا يُتحقق من الصيغة: استخدم هذه الصيغة فقط. مثال `2026-01-31`
`stage`	`string`	اختياري	تصفية حسب `stage` للطرد. هذه القيم الست فقط تُصفّي؛ وأي قيمة أخرى (ومنها `processing` و`awaiting_funds` والأخطاء الإملائية) تُتجاهل بصمت ويعود كل شيء دون تصفية. إحدى القيم: `pending` `out_for_delivery` `delivered` `partially_delivered` `returning` `returned` مثال `out_for_delivery`
`per_page`	`integer`	اختياري	حجم الصفحة من 1 إلى 100 (الافتراضي 20). القيمة خارج المجال لا تُرفض بل تُقرَّب إلى أقرب حدّ، وتعود القيمة الفعلية في `meta.per_page`. الحد الأدنى 1الحد الأقصى 100الافتراضي `20`
`page`	`integer`	اختياري	رقم الصفحة ويبدأ من 1. القيمة غير الصالحة أو الأصغر من 1 تُعامل على أنها 1. والصفحة بعد الأخيرة تعيد قائمة فارغة. الحد الأدنى 1الافتراضي `1`

الردود

200 صفحة من الطرود.

صفحة من الطرود.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`array<Parcel>`	مطلوب
`meta`	`Meta`	مطلوب	كتلة الترقيم. لا توجد روابط ولا مؤشر (cursor).

مثال

JSON · 200

{
  "success": true,
  "data": [
    {
      "id": 1043,
      "tracking_number": "DS-000000",
      "reference": "ORDER-1043",
      "stage": "out_for_delivery",
      "status_code": 7,
      "status_label": "Delivery Man Assign",
      "company_id": 3,
      "company_name": "Example Delivery",
      "external_tracking_number": null,
      "recipient": {
        "name": "Example Name",
        "phone": "0900000000",
        "governorate": "Damascus",
        "address": "Example street, building 1",
        "lat": null,
        "lng": null
      },
      "cod_amount": 25,
      "cod_collected": 0,
      "weight_kg": 1.5,
      "charges": {
        "delivery_fee": 6,
        "platform_fee": 1
      },
      "delivery_attempts": 0,
      "note": null,
      "tracking_url": "https://YOUR_DOMAIN/t/DS-000000",
      "created_at": "2026-01-01T10:00:00+00:00",
      "updated_at": "2026-01-01T12:10:00+00:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X GET "https://YOUR_DOMAIN/api/v1/parcels?reference=ORDER-1043&from=2026-01-01&to=2026-01-31&stage=out_for_delivery" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/parcels?reference=ORDER-1043&from=2026-01-01&to=2026-01-31&stage=out_for_delivery");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
    ],
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/parcels?reference=ORDER-1043&from=2026-01-01&to=2026-01-31&stage=out_for_delivery", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
  },
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.get(
    "https://YOUR_DOMAIN/api/v1/parcels",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    params={
        "reference": "ORDER-1043",
        "from": "2026-01-01",
        "to": "2026-01-31",
        "stage": "out_for_delivery",
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

الطريقة POST `/parcels` #

إنشاء طرد

تنشئ طرداً. تُحسب أجرة التوصيل على الخادم وتُخصم من محفظتك. أرسل reference نفسه مجدداً لإعادة المحاولة بأمان: تحصل على الطرد الموجود مع "duplicate": true (HTTP 200) ولا يُخصم أي مبلغ (الطرود المستردّة أو المنتهية لا تُحتسب). لا توجد ترويسة Idempotency-Key. التاجر بلا باقة فعّالة يُرفض بالرمز plan_feature قبل معالجة الطرد، وبلوغ حصة الطرود يعطي 422 على الحقل plan. وإذا رفضت شركة شحن خارجية الطرد فلا يُنشأ شيء ولا يُخصم شيء (carrier_error).

الطلب POST /api/v1/parcels
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها، و60 لهذا المسار
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة مرجع واجهة التاجر API v1 إصدارات الواجهة وإعادة المحاولة الآمنة (Idempotency)

جسم الطلب

application/json · مطلوب

الحقل	النوع	مطلوب	الوصف
`company_id`	`integer`	مطلوب	شركة التوصيل أو الشحن، قيمة `id` من `GET /companies`. يجب أن تكون متاحة لحسابك.
`recipient`	`object`	مطلوب	المستلم. يمكن بدلاً من ذلك إرسال كل حقل مسطحاً في المستوى الأعلى (`customer_name` و`customer_phone` و`customer_address` و`customer_city` و`lat` و`long`)؛ والشكل المتداخل هو الموثَّق.
`name`	`string`	مطلوب	اسم المستلم. الحد الأقصى للطول 191
`phone`	`string`	مطلوب	رقم هاتف المستلم: أرقام ومسافات و`+` و`-` وأقواس، من 6 إلى 30 محرفاً. الحد الأقصى للطول 30النمط `^[+0-9\s\-()]{6,30}$`
`address`	`string`	مطلوب	عنوان المستلم. الحد الأقصى للطول 1000
`governorate`	`string`	اختياري	اسم المحافظة (`name` بالإنجليزية أو `name_ar` بالعربية من `GET /governorates`). وإن أرسلت المعرّف فأرسله نصاً مثل `"3"` لأن الرقم في JSON يُرفض. مطلوب للتسعير حسب المحافظة، وإلا تحاول المنصة استنتاجها من العنوان ثم من الإحداثيات. الحد الأقصى للطول 120يُقبل أيضاً باسم `customer_city, city`
`lat`	`number`	اختياري	خط عرض موقع المستلم. مطلوب للتسعير حسب المسافة (`per_km` و`km_kg`). الحد الأدنى -90الحد الأقصى 90
`lng`	`number`	اختياري	خط طول موقع المستلم. مطلوب للتسعير حسب المسافة (`per_km` و`km_kg`). الحد الأدنى -180الحد الأقصى 180يُقبل أيضاً باسم `long`
`reference`	`string`	اختياري	مرجعك الخاص الفريد (رقم الطلب) بحد أقصى 191 محرفاً. يجعل إعادة المحاولة آمنة: إرسال المرجع نفسه مجدداً يُرجع الطرد الموجود مع `"duplicate": true` بدل إنشاء طرد جديد. الحد الأقصى للطول 191يُقبل أيضاً باسم `invoice_no`
`cod_amount`	`number`	اختياري	مبلغ التحصيل عند الاستلام الذي يدفعه المستلم، من 0 إلى 100,000,000 دولار أمريكي (يُحوَّل المبلغ بغير الدولار إلى الدولار بسعر المنصة قبل فحص الحد). القيمة 0 تعني مدفوع مسبقاً. الحد الأدنى 0الحد الأقصى 100000000الافتراضي `0`
`currency`	`string`	اختياري	رمز عملة `cod_amount` (لا فرق بين الأحرف الكبيرة والصغيرة). يُخزَّن المبلغ بالدولار، لذا يكون `cod_amount` في كائنات الطرد بالدولار دائماً. وقد لا تقبل الشركة إلا بعض العملات. وغياب سعر الصرف يعطي `422`. إحدى القيم: `USD` `SYP` `SAR` `AED` `QAR` `KWD` `JOD` `IQD` `EGP` `LBP` `TRY` `EUR` الافتراضي `USD`يُقبل أيضاً باسم `cod_currency`
`weight`	`number`	اختياري	الوزن بالكيلوغرام من 0.01 إلى 1000. الافتراضي 1. في التسعير الداخلي يُقرَّب الوزن إلى كيلوغرام كامل (الحد الأدنى 1). الحد الأدنى 0.01الحد الأقصى 1000الافتراضي `1`يُقبل أيضاً باسم `weight_kg`
`pickup_location_id`	`integer`	اختياري	أحد أماكن الاستلام لديك (`GET /pickup-locations`). يُستخدم مكانك الافتراضي عند عدم الإرسال. وتُبلَّغ الأخطاء على الحقل `shop_id`. يُقبل أيضاً باسم `shop_id`
`warehouse_items`	`array<object>`	اختياري	المنتجات التي تُشحن من مخزونك. مطلوبة عندما يكون مكان الاستلام مستودعاً، وتُهمل في غير ذلك. وتُقبل أيضاً باسم `items`. يُقبل أيضاً باسم `items`
`sku`	`string`	اختياري	رمز المنتج (SKU) في المخزون.
`item_id`	`integer`	اختياري	معرّف صنف المخزون (بديل لـ `sku`).
`qty`	`integer`	مطلوب	الكمية التي تخرج مع الطرد؛ يجب ألا تتجاوز الكمية المتاحة. الحد الأدنى 1
`note`	`string`	اختياري	ملاحظة لشركة التوصيل بحد أقصى 2000 محرف. الحد الأقصى للطول 2000
`use_own_account`	`boolean`	اختياري	الشحن بحسابك الخاص لدى شركة شحن تسمح بحسابات التجّار. يفشل بالرمز `carrier_error` إن كانت الشركة تسمح بها ولم تربط حسابك، ويُتجاهل إن كانت لا تسمح بها، ولا أثر له على شركات التوصيل.
`shipping_paid_by`	`string`	اختياري	من يدفع أجرة الشحن، لشركات الشحن التي تدعم الاختيار: `sender` (المرسل) أو `customer` (المستلم) أو `included_in_cod` (ضمن مبلغ التحصيل). إحدى القيم: `sender` `customer` `included_in_cod`
`wait_for_balance`	`boolean`	اختياري	عند عدم كفاية رصيد المحفظة يُحفظ الطرد بالمرحلة `awaiting_funds` (الرد `201` ويُخفى عن `GET /parcels`) بدل الفشل بالرمز `402`. تُكمله مهمة كل ساعة عند توفر الرصيد وتلغيه بعد 24 ساعة.

مثال

JSON

{
  "company_id": 3,
  "reference": "ORDER-1043",
  "recipient": {
    "name": "Example Name",
    "phone": "0900000000",
    "governorate": "Damascus",
    "address": "Example street, building 1"
  },
  "cod_amount": 25,
  "weight": 1.5,
  "note": "Call before arriving"
}

الردود

200 يوجد طرد بالمرجع reference نفسه:

يوجد طرد بالمرجع reference نفسه: يُرجع كما هو مع duplicate: true.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`Parcel`	مطلوب	الطرد كما ترجعه الواجهة وكما تحمله رسائل الويب هوك (الحقول نفسها دائماً).
`duplicate`	`boolean`	مطلوب	قيمة ثابتة `true`

مثال

JSON · 200

{
  "success": true,
  "data": {
    "id": 1043,
    "tracking_number": "DS-000000",
    "reference": "ORDER-1043",
    "stage": "out_for_delivery",
    "status_code": 7,
    "status_label": "Delivery Man Assign",
    "company_id": 3,
    "company_name": "Example Delivery",
    "external_tracking_number": null,
    "recipient": {
      "name": "Example Name",
      "phone": "0900000000",
      "governorate": "Damascus",
      "address": "Example street, building 1",
      "lat": null,
      "lng": null
    },
    "cod_amount": 25,
    "cod_collected": 0,
    "weight_kg": 1.5,
    "charges": {
      "delivery_fee": 6,
      "platform_fee": 1
    },
    "delivery_attempts": 0,
    "note": null,
    "tracking_url": "https://YOUR_DOMAIN/t/DS-000000",
    "created_at": "2026-01-01T10:00:00+00:00",
    "updated_at": "2026-01-01T12:10:00+00:00"
  },
  "duplicate": true
}

201 تم إنشاء الطرد.

تم إنشاء الطرد.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`Parcel`	مطلوب	الطرد كما ترجعه الواجهة وكما تحمله رسائل الويب هوك (الحقول نفسها دائماً).

مثال

JSON · 201

{
  "success": true,
  "data": {
    "id": 1043,
    "tracking_number": "DS-000000",
    "reference": "ORDER-1043",
    "stage": "processing",
    "status_code": 5,
    "status_label": "Received Warehouse",
    "company_id": 3,
    "company_name": "Example Delivery",
    "external_tracking_number": null,
    "recipient": {
      "name": "Example Name",
      "phone": "0900000000",
      "governorate": "Damascus",
      "address": "Example street, building 1",
      "lat": null,
      "lng": null
    },
    "cod_amount": 25,
    "cod_collected": 0,
    "weight_kg": 1.5,
    "charges": {
      "delivery_fee": 6,
      "platform_fee": 1
    },
    "delivery_attempts": 0,
    "note": null,
    "tracking_url": "https://YOUR_DOMAIN/t/DS-000000",
    "created_at": "2026-01-01T10:00:00+00:00",
    "updated_at": "2026-01-01T12:10:00+00:00"
  }
}

402 insufficient_balance:

insufficient_balance: رصيد المحفظة لا يكفي (تذكر الرسالة المبلغ المطلوب والمتاح). أرسل wait_for_balance: true لحفظ الطرد بالمرحلة awaiting_funds بدلاً من ذلك.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

مثال — Balance too low

JSON · 402

{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient wallet balance. Required: 7.00, available: 2.00"
  }
}

422 validation_failed:

validation_failed: حقل مفقود أو خاطئ (يسردها fields بأسماء المنصة الداخلية)، أو company_id غير متاح لك، أو استُنفدت الحصة (plan). carrier_error: رفضت شركة الشحن الخارجية الطرد أو أن حساب الشركة غير صالح للاستخدام.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

مثال — Missing recipient phone

JSON · 422

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "The customer phone field is required.",
    "fields": {
      "customer_phone": [
        "The customer phone field is required."
      ]
    }
  }
}

مثال — Carrier refused

JSON · 422

{
  "success": false,
  "error": {
    "code": "carrier_error",
    "message": "Localized message from the carrier."
  }
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X POST "https://YOUR_DOMAIN/api/v1/parcels" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "company_id": 3,
  "reference": "ORDER-1043",
  "recipient": {
    "name": "Example Name",
    "phone": "0900000000",
    "governorate": "Damascus",
    "address": "Example street, building 1"
  },
  "cod_amount": 25,
  "weight": 1.5,
  "note": "Call before arriving"
}'

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/parcels");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'company_id' => 3,
        'reference' => 'ORDER-1043',
        'recipient' => [
            'name' => 'Example Name',
            'phone' => '0900000000',
            'governorate' => 'Damascus',
            'address' => 'Example street, building 1',
        ],
        'cod_amount' => 25,
        'weight' => 1.5,
        'note' => 'Call before arriving',
    ]),
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/parcels", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "company_id": 3,
    "reference": "ORDER-1043",
    "recipient": {
      "name": "Example Name",
      "phone": "0900000000",
      "governorate": "Damascus",
      "address": "Example street, building 1"
    },
    "cod_amount": 25,
    "weight": 1.5,
    "note": "Call before arriving"
  }),
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.post(
    "https://YOUR_DOMAIN/api/v1/parcels",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    json={
        "company_id": 3,
        "reference": "ORDER-1043",
        "recipient": {
            "name": "Example Name",
            "phone": "0900000000",
            "governorate": "Damascus",
            "address": "Example street, building 1",
        },
        "cod_amount": 25,
        "weight": 1.5,
        "note": "Call before arriving",
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

الطريقة GET `/parcels/{tracking}` #

جلب طرد واحد مع أحداثه

تأخذ رقم تتبع أو reference (يُعتمد أحدث تطابق) وتُرجع الطرد مع events بترتيب زمني. وتجد أيضاً الطرود في المرحلة awaiting_funds.

الطلب GET /api/v1/parcels/{tracking}
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة مرجع واجهة التاجر API v1

معاملات المسار

الاسم النوع مطلوب الوصف

الاسم	النوع	مطلوب	الوصف
`tracking`	`string`	مطلوب	رقم التتبع، أو `reference` الذي أرسلته عند إنشاء الطرد (يُعتمد أحدث تطابق؛ وقد يشير المرجع إلى طرد غير الذي تقصده، لذا ألغِ برقم التتبع). مثال `DS-000000`

tracking

string

مطلوب

رقم التتبع، أو reference الذي أرسلته عند إنشاء الطرد (يُعتمد أحدث تطابق؛ وقد يشير المرجع إلى طرد غير الذي تقصده، لذا ألغِ برقم التتبع).

مثال DS-000000

الردود

200 الطرد مع أحداثه.

الطرد مع أحداثه.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`object`	مطلوب	كائن الطرد مع تاريخه (`events`). يُرجَع عند جلب طرد واحد.
يتضمن كل حقول `Parcel`
`events`	`array<object>`	مطلوب	تاريخ الطرد بترتيب زمني. يظهر فقط عند جلب طرد واحد.
`status_code`	`integer`	مطلوب	رمز الحالة الداخلي الدقيق لتلك الخطوة.
`stage`	`string`	مطلوب	المرحلة المبسطة لتلك الخطوة. إحدى القيم: `pending` `processing` `out_for_delivery` `delivered` `partially_delivered` `returning` `returned`
`status_label`	`string`	مطلوب	تسمية الحالة بلغة الطلب.
`note`	`string` \| null	مطلوب	ملاحظة نصية مسجّلة مع الحدث.
`at`	`string (date-time)` \| null	مطلوب	وقت الحدث (ISO 8601 مع فرق التوقيت عن UTC).

مثال

JSON · 200

{
  "success": true,
  "data": {
    "id": 1043,
    "tracking_number": "DS-000000",
    "reference": "ORDER-1043",
    "stage": "out_for_delivery",
    "status_code": 7,
    "status_label": "Delivery Man Assign",
    "company_id": 3,
    "company_name": "Example Delivery",
    "external_tracking_number": null,
    "recipient": {
      "name": "Example Name",
      "phone": "0900000000",
      "governorate": "Damascus",
      "address": "Example street, building 1",
      "lat": null,
      "lng": null
    },
    "cod_amount": 25,
    "cod_collected": 0,
    "weight_kg": 1.5,
    "charges": {
      "delivery_fee": 6,
      "platform_fee": 1
    },
    "delivery_attempts": 0,
    "note": null,
    "tracking_url": "https://YOUR_DOMAIN/t/DS-000000",
    "created_at": "2026-01-01T10:00:00+00:00",
    "updated_at": "2026-01-01T12:10:00+00:00",
    "events": [
      {
        "status_code": 1,
        "stage": "pending",
        "status_label": "Pending",
        "note": "Parcel created (api)",
        "at": "2026-01-01T10:00:00+00:00"
      },
      {
        "status_code": 5,
        "stage": "processing",
        "status_label": "Received Warehouse",
        "note": null,
        "at": "2026-01-01T10:00:01+00:00"
      }
    ]
  }
}

404 not_found:

not_found: لا يوجد طرد بهذا الرقم أو المرجع في حسابك (والطرد الملغى لم يعد موجوداً).

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

مثال — Unknown parcel

JSON · 404

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "No parcel with this number for your account."
  }
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X GET "https://YOUR_DOMAIN/api/v1/parcels/DS-000000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/parcels/DS-000000");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
    ],
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/parcels/DS-000000", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
  },
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.get(
    "https://YOUR_DOMAIN/api/v1/parcels/DS-000000",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

الطريقة POST `/parcels/{tracking}/cancel` #

إلغاء طرد واسترجاع الأجرة

تلغي الطرد وتسترجع ما خُصم عند الإنشاء. لا تعمل إلا ما دامت الحالة «معلّق» أو «مستلم في المستودع» وليس للطرد external_tracking_number. يُحذف الطرد (والاستدعاء الثاني يعطي 404). والإلغاء عبر الـ API لا يرسل ويب هوك parcel.cancelled.

الطلب POST /api/v1/parcels/{tracking}/cancel
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة مرجع واجهة التاجر API v1 إصدارات الواجهة وإعادة المحاولة الآمنة (Idempotency)

معاملات المسار

الاسم النوع مطلوب الوصف

الاسم	النوع	مطلوب	الوصف
`tracking`	`string`	مطلوب	رقم التتبع، أو `reference` الذي أرسلته عند إنشاء الطرد (يُعتمد أحدث تطابق؛ وقد يشير المرجع إلى طرد غير الذي تقصده، لذا ألغِ برقم التتبع). مثال `DS-000000`

tracking

string

مطلوب

رقم التتبع، أو reference الذي أرسلته عند إنشاء الطرد (يُعتمد أحدث تطابق؛ وقد يشير المرجع إلى طرد غير الذي تقصده، لذا ألغِ برقم التتبع).

مثال DS-000000

الردود

200 أُلغي الطرد واستُرجعت الأجرة.

أُلغي الطرد واستُرجعت الأجرة.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`object`	مطلوب	نتيجة الإلغاء.
`tracking_number`	`string`	مطلوب	رقم تتبع الطرد الملغى.
`cancelled`	`boolean`	مطلوب	قيمة ثابتة `true`
`refunded`	`boolean`	مطلوب	قيمة ثابتة `true`

مثال

JSON · 200

{
  "success": true,
  "data": {
    "tracking_number": "DS-000000",
    "cancelled": true,
    "refunded": true
  }
}

404 not_found:

not_found: لا يوجد طرد بهذا الرقم في حسابك.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

مثال — Unknown parcel

JSON · 404

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "No parcel with this number for your account."
  }
}

409 not_cancellable:

not_cancellable: خرج الطرد من الحالة «معلّق» أو «مستلم في المستودع»، أو أُرسل إلى شركة شحن خارجية.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

مثال — Already on its way

JSON · 409

{
  "success": false,
  "error": {
    "code": "not_cancellable",
    "message": "The parcel is out for delivery or sent to the shipping company — it cannot be cancelled from here."
  }
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X POST "https://YOUR_DOMAIN/api/v1/parcels/DS-000000/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/parcels/DS-000000/cancel");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
    ],
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/parcels/DS-000000/cancel", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
  },
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.post(
    "https://YOUR_DOMAIN/api/v1/parcels/DS-000000/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

كشف الحساب

كشف حساب المحفظة لفترة.

الطريقة GET `/statement` #

جلب كشف حساب المحفظة

كشف حساب محفظتك لفترة: الرصيد الافتتاحي والختامي لكل محفظة، وملخص لكل نوع حركة، وكل الحركات (الأقدم أولاً). المبالغ بالدولار. الرد مرقّم: meta يعدّ lines، أما wallets وby_category فتغطيان الفترة كلها.

الطلب GET /api/v1/statement
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها، و30 لهذا المسار
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة مرجع واجهة التاجر API v1

معاملات الاستعلام

الاسم	النوع	مطلوب	الوصف
`from`	`string (date)`	اختياري	أول يوم `YYYY-MM-DD`. الافتراضي: أول يوم في الشهر الحالي. يُقبل بصيغة `YYYY-MM-DD` حرفياً فقط وإلا يُتجاهل. وإذا جاء `from` بعد `to` تُبدَّل القيمتان، والمدى الأطول من 366 يوماً يُقصَّر بتحريك `from`. مثال `2026-01-01`
`to`	`string (date)`	اختياري	آخر يوم `YYYY-MM-DD`. الافتراضي: اليوم. بالقواعد نفسها المطبّقة على `from`. مثال `2026-01-31`
`wallet`	`string`	اختياري	هذه المحفظة فقط: `recharge` (رصيد الشحن) أو `held` (المبالغ المحجوزة) أو `return` (مستحقات التحصيل) أو `payout_pending`. أي قيمة أخرى تُتجاهل. إحدى القيم: `recharge` `held` `return` `payout_pending`
`category`	`string`	اختياري	هذا النوع من الحركات فقط، مثل `parcel_created`. أحرف لاتينية صغيرة وشرطات سفلية (من 2 إلى 60 محرفاً)؛ ولا يُتحقق منه من قائمة الأنواع المعروفة، فالقيمة المجهولة لا تعيد أي سطر. النمط `^[a-z_]{2,60}$` مثال `parcel_created`
`per_page`	`integer`	اختياري	حجم الصفحة من 1 إلى 500 (الافتراضي 100). القيمة خارج المجال لا تُرفض بل تُقرَّب إلى أقرب حدّ، وتعود القيمة الفعلية في `meta.per_page`. الحد الأدنى 1الحد الأقصى 500الافتراضي `100`
`page`	`integer`	اختياري	رقم الصفحة ويبدأ من 1. القيمة غير الصالحة أو الأصغر من 1 تُعامل على أنها 1. والصفحة بعد الأخيرة تعيد قائمة فارغة. الحد الأدنى 1الافتراضي `1`

الردود

200 كشف الحساب.

كشف الحساب.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`object`	مطلوب	كشف المحفظة لفترة. كل المبالغ بالدولار.
`period`	`object`	مطلوب	الفترة المطبّقة فعلياً.
`from`	`string (date)`	مطلوب	أول يوم (`YYYY-MM-DD`).
`to`	`string (date)`	مطلوب	آخر يوم (`YYYY-MM-DD`).
`currency`	`string`	مطلوب	قيمة ثابتة `"USD"`
`wallets`	`array<object>`	مطلوب	الرصيد الافتتاحي والختامي لكل محفظة. تغطي الفترة كلها بصرف النظر عن الصفحة.
`wallet`	`string`	مطلوب	رمز المحفظة. إحدى القيم: `recharge` `held` `return` `payout_pending`
`name`	`string`	مطلوب	تسمية المحفظة بلغة الطلب.
`opening`	`number`	مطلوب	الرصيد قبل الفترة.
`credits`	`number`	مطلوب	مجموع الإيداعات في الفترة.
`debits`	`number`	مطلوب	مجموع السحوبات في الفترة.
`closing`	`number`	مطلوب	الرصيد في نهاية الفترة.
`count`	`integer`	مطلوب	عدد الحركات.
`by_category`	`array<object>`	مطلوب	ملخص لكل نوع حركة. يغطي الفترة كلها بصرف النظر عن الصفحة.
`category`	`string`	مطلوب	رمز نوع الحركة، مثل `parcel_created`.
`name`	`string`	مطلوب	تسمية النوع بلغة الطلب.
`credits`	`number`	مطلوب	إيداعات هذا النوع.
`debits`	`number`	مطلوب	سحوبات هذا النوع.
`count`	`integer`	مطلوب	عدد الحركات.
`lines`	`array<object>`	مطلوب	حركات الصفحة المطلوبة، الأقدم أولاً (التاريخ ثم المعرّف). يسري الترقيم على هذه القائمة فقط.
`id`	`integer`	مطلوب	معرّف الحركة.
`date`	`string (date-time)`	مطلوب	وقت الحركة (ISO 8601).
`wallet`	`string`	مطلوب	رمز المحفظة.
`wallet_name`	`string`	مطلوب	تسمية المحفظة.
`type`	`string`	مطلوب	رمز نوع الحركة.
`type_name`	`string`	مطلوب	تسمية النوع.
`credit`	`number`	مطلوب	مبلغ الإيداع (0 للسحب).
`debit`	`number`	مطلوب	مبلغ السحب (0 للإيداع).
`balance`	`number`	مطلوب	رصيد المحفظة بعد الحركة.
`description`	`string` \| null	مطلوب	وصف الحركة.
`parcel`	`string` \| null	مطلوب	رقم التتبع عندما تتعلق الحركة بطرد.
`meta`	`Meta`	مطلوب	كتلة الترقيم. لا توجد روابط ولا مؤشر (cursor).

مثال

JSON · 200

{
  "success": true,
  "data": {
    "period": {
      "from": "2026-01-01",
      "to": "2026-01-31"
    },
    "currency": "USD",
    "wallets": [
      {
        "wallet": "recharge",
        "name": "Shipping balance",
        "opening": 50,
        "credits": 200,
        "debits": 132.5,
        "closing": 117.5,
        "count": 41
      }
    ],
    "by_category": [
      {
        "category": "parcel_created",
        "name": "Parcel creation fee",
        "credits": 0,
        "debits": 132.5,
        "count": 38
      }
    ],
    "lines": [
      {
        "id": 9811,
        "date": "2026-01-02T10:14:00+00:00",
        "wallet": "recharge",
        "wallet_name": "Shipping balance",
        "type": "parcel_created",
        "type_name": "Parcel creation fee",
        "credit": 0,
        "debit": 3.5,
        "balance": 46.5,
        "description": "Example description",
        "parcel": "DS-000000"
      }
    ]
  },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X GET "https://YOUR_DOMAIN/api/v1/statement?from=2026-01-01&to=2026-01-31&category=parcel_created" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/statement?from=2026-01-01&to=2026-01-31&category=parcel_created");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
    ],
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/statement?from=2026-01-01&to=2026-01-31&category=parcel_created", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
  },
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.get(
    "https://YOUR_DOMAIN/api/v1/statement",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    params={
        "from": "2026-01-01",
        "to": "2026-01-31",
        "category": "parcel_created",
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

روابط الويب هوك

إدارة العناوين التي تستقبل إشعاراتك. أما الرسائل نفسها فمشروحة ضمن أحداث الويب هوك.

الطريقة GET `/webhooks/events` #

قائمة الأحداث التي يمكنك الاشتراك بها

تعرض أسماء الأحداث مع اسمها المختصر ووصفها بلغة الطلب. أرسل * أو أسماءً بعينها في events عند إنشاء الرابط. لا تُعرض ping لأنها لا تُختار.

الطلب GET /api/v1/webhooks/events
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة الويب هوك الصادر: إشعارات فورية لنظامك

الردود

200 الأحداث.

الأحداث.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`array<object>`	مطلوب
`event`	`string`	مطلوب	اسم الحدث. إحدى القيم: `parcel.created` `parcel.status_changed` `parcel.out_for_delivery` `parcel.delivered` `parcel.returning` `parcel.returned` `parcel.cancelled` `parcel.awaiting_funds` `wallet.topup` `wallet.withdrawal`
`name`	`string`	مطلوب	اسم مختصر بلغة الطلب.
`description`	`string`	مطلوب	متى يُرسل، بلغة الطلب.

مثال

JSON · 200

{
  "success": true,
  "data": [
    {
      "event": "parcel.delivered",
      "name": "Delivered",
      "description": "The parcel was delivered (fully or partially) — includes the collected amount."
    }
  ]
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X GET "https://YOUR_DOMAIN/api/v1/webhooks/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/webhooks/events");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
    ],
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/webhooks/events", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
  },
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.get(
    "https://YOUR_DOMAIN/api/v1/webhooks/events",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

الطريقة GET `/webhooks` #

قائمة روابط الويب هوك لديك

تعرض روابط الويب هوك لديك. لا يُرجَع مفتاح التوقيع أبداً. القائمة غير مرقّمة.

الطلب GET /api/v1/webhooks
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة الويب هوك الصادر: إشعارات فورية لنظامك

الردود

200 روابطك.

روابطك.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`array<Webhook>`	مطلوب

مثال

JSON · 200

{
  "success": true,
  "data": [
    {
      "id": 7,
      "name": "ERP",
      "url": "https://example.com/hooks/delivery",
      "events": [
        "parcel.delivered",
        "parcel.returned"
      ],
      "active": true,
      "disabled_reason": null,
      "last_status": null,
      "last_error": null,
      "last_sent_at": null
    }
  ]
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X GET "https://YOUR_DOMAIN/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/webhooks");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
    ],
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/webhooks", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
  },
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.get(
    "https://YOUR_DOMAIN/api/v1/webhooks",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

الطريقة POST `/webhooks` #

إضافة رابط ويب هوك

تنشئ رابطاً وتُرجع مفتاح توقيعه (secret) مرة واحدة. تحتاج باقة فيها ميزة الويب هوك (403 plan_feature) وتتيح 10 روابط كحد أقصى، أو حدّ باقتك إن كان أقل (422 limit_reached). يجب أن يكون العنوان https وعاماً وبلا اسم مستخدم أو كلمة مرور وعلى المنفذ 443 أو 8443. وطريقة توقيع الرسائل وإعادة إرسالها في مقالات الويب هوك.

الطلب POST /api/v1/webhooks
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها، و20 لهذا المسار
يتطلب ميزة الباقة: الـ API + الويب هوك (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة الويب هوك الصادر: إشعارات فورية لنظامك التحقق من توقيع الويب هوك (X-DS-Signature)

جسم الطلب

application/json · مطلوب

الحقل	النوع	مطلوب	الوصف
`name`	`string` \| null	اختياري	تسمية اختيارية بحد أقصى 100 محرف. الحد الأقصى للطول 100
`url`	`string (uri)`	مطلوب	عنوان HTTPS بحد أقصى 500 محرف. يجب أن يُحلّ النطاق إلى عناوين عامة فقط، دون اسم مستخدم أو كلمة مرور، وعلى المنفذ 443 أو 8443. ولا تُتبع التحويلات. الحد الأقصى للطول 500النمط `^[Hh][Tt][Tt][Pp][Ss]://`
`events`	`array<string>`	مطلوب	الأحداث المطلوب استقبالها: عنصر واحد على الأقل، كل منها `` أو اسم حدث بعينه. إحدى القيم: `` `parcel.created` `parcel.status_changed` `parcel.out_for_delivery` `parcel.delivered` `parcel.returning` `parcel.returned` `parcel.cancelled` `parcel.awaiting_funds` `wallet.topup` `wallet.withdrawal` الحد الأدنى للعناصر 1
`active`	`boolean`	اختياري	هل الرابط مفعّل (الافتراضي true).

مثال

JSON

{
  "name": "ERP",
  "url": "https://example.com/hooks/delivery",
  "events": [
    "parcel.delivered",
    "parcel.returned"
  ]
}

الردود

201 تم إنشاء الرابط.

تم إنشاء الرابط.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`object`	مطلوب	رابط ويب هوك مع مفتاح التوقيع (يظهر مرة واحدة).
`id`	`integer`	مطلوب	معرّف الرابط.
`name`	`string` \| null	مطلوب	التسمية التي أعطيتها للرابط.
`url`	`string`	مطلوب	عنوان HTTPS الذي يستقبل الرسائل.
`events`	`array<string>`	مطلوب	الأحداث المشترك بها؛ `["*"]` تعني كل الأحداث.
`active`	`boolean`	مطلوب	تكون false عند التعطيل، ومنه الإيقاف التلقائي بعد 40 محاولة فاشلة متتالية.
`disabled_reason`	`string` \| null	مطلوب	سبب إيقاف الرابط تلقائياً.
`last_status`	`integer` \| null	مطلوب	حالة HTTP لآخر محاولة إرسال.
`last_error`	`string` \| null	مطلوب	خطأ آخر محاولة فاشلة.
`last_sent_at`	`string (date-time)` \| null	مطلوب	وقت آخر محاولة (ISO 8601).
`secret`	`string`	مطلوب	مفتاح التوقيع (`whsec_` يليه 40 محرفاً). يُرجع في هذا الرد فقط: احفظه الآن.

مثال

JSON · 201

{
  "success": true,
  "data": {
    "id": 7,
    "name": "ERP",
    "url": "https://example.com/hooks/delivery",
    "events": [
      "parcel.delivered",
      "parcel.returned"
    ],
    "active": true,
    "disabled_reason": null,
    "last_status": null,
    "last_error": null,
    "last_sent_at": null,
    "secret": "whsec_EXAMPLE_ONLY_NOT_A_REAL_SECRET"
  }
}

422 validation_failed:

validation_failed: حقل مفقود أو خاطئ (يجب أن يكون العنوان https وعاماً وعلى المنفذ 443 أو 8443، وكل حدث * أو اسماً بعينه). limit_reached: لديك أصلاً العدد الأقصى من الروابط.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

مثال — Not https

JSON · 422

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "The URL must start with https://",
    "fields": {
      "url": [
        "The URL must start with https://"
      ]
    }
  }
}

مثال — Too many endpoints

JSON · 422

{
  "success": false,
  "error": {
    "code": "limit_reached",
    "message": "You have reached your plan limit: 10 webhook links."
  }
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X POST "https://YOUR_DOMAIN/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "ERP",
  "url": "https://example.com/hooks/delivery",
  "events": [
    "parcel.delivered",
    "parcel.returned"
  ]
}'

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/webhooks");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'name' => 'ERP',
        'url' => 'https://example.com/hooks/delivery',
        'events' => [
            'parcel.delivered',
            'parcel.returned',
        ],
    ]),
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "ERP",
    "url": "https://example.com/hooks/delivery",
    "events": [
      "parcel.delivered",
      "parcel.returned"
    ]
  }),
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.post(
    "https://YOUR_DOMAIN/api/v1/webhooks",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    json={
        "name": "ERP",
        "url": "https://example.com/hooks/delivery",
        "events": [
            "parcel.delivered",
            "parcel.returned",
        ],
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

الطريقة DELETE `/webhooks/{id}` #

حذف رابط ويب هوك

تحذف الرابط. الرسائل التي ما زالت بانتظار إعادة الإرسال تُعلَّم فاشلة عند حلول موعدها.

الطلب DELETE /api/v1/webhooks/{id}
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة الويب هوك الصادر: إشعارات فورية لنظامك

معاملات المسار

الاسم النوع مطلوب الوصف

الاسم	النوع	مطلوب	الوصف
`id`	`integer`	مطلوب	معرّف رابط الويب هوك (من `GET /webhooks`). مثال `7`

id

integer

مطلوب

معرّف رابط الويب هوك (من GET /webhooks).

مثال 7

الردود

200 تم حذف الرابط.

تم حذف الرابط.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`object`	مطلوب	نتيجة الحذف.
`deleted`	`boolean`	مطلوب	قيمة ثابتة `true`

مثال

JSON · 200

{
  "success": true,
  "data": {
    "deleted": true
  }
}

404 not_found:

not_found: لا يوجد هذا الرابط في حسابك.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

مثال — Unknown webhook endpoint

JSON · 404

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Link not found."
  }
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X DELETE "https://YOUR_DOMAIN/api/v1/webhooks/7" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/webhooks/7");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "DELETE",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
    ],
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/webhooks/7", {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
  },
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.delete(
    "https://YOUR_DOMAIN/api/v1/webhooks/7",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

الطريقة PATCH `/webhooks/{id}` #

تعديل رابط ويب هوك

تعدّل name أو url أو events أو active؛ أرسل ما تريد تغييره فقط. تفعيل active من جديد يصفّر عدّاد الإخفاق ويمسح سبب الإيقاف.

الطلب PATCH /api/v1/webhooks/{id}
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة الويب هوك الصادر: إشعارات فورية لنظامك إعادة محاولة الويب هوك والإيقاف التلقائي

معاملات المسار

الاسم النوع مطلوب الوصف

الاسم	النوع	مطلوب	الوصف
`id`	`integer`	مطلوب	معرّف رابط الويب هوك (من `GET /webhooks`). مثال `7`

id

integer

مطلوب

معرّف رابط الويب هوك (من GET /webhooks).

مثال 7

جسم الطلب

application/json · مطلوب

الحقل	النوع	مطلوب	الوصف
`name`	`string` \| null	اختياري	التسمية بحد أقصى 100 محرف. الحد الأقصى للطول 100
`url`	`string (uri)`	اختياري	عنوان HTTPS الجديد (بالقواعد نفسها عند الإنشاء). الحد الأقصى للطول 500النمط `^[Hh][Tt][Tt][Pp][Ss]://`
`events`	`array<string>`	اختياري	القائمة الجديدة للأحداث (واحد على الأقل). إحدى القيم: `*` `parcel.created` `parcel.status_changed` `parcel.out_for_delivery` `parcel.delivered` `parcel.returning` `parcel.returned` `parcel.cancelled` `parcel.awaiting_funds` `wallet.topup` `wallet.withdrawal` الحد الأدنى للعناصر 1
`active`	`boolean`	اختياري	تفعيله من جديد يصفّر عدّاد الإخفاق ويمسح سبب الإيقاف.

مثال

JSON

{
  "active": true
}

الردود

200 الرابط بعد التعديل.

الرابط بعد التعديل.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`Webhook`	مطلوب	رابط ويب هوك (لا يُرجَع مفتاح التوقيع أبداً).

مثال

JSON · 200

{
  "success": true,
  "data": {
    "id": 7,
    "name": "ERP",
    "url": "https://example.com/hooks/delivery",
    "events": [
      "parcel.delivered",
      "parcel.returned"
    ],
    "active": true,
    "disabled_reason": null,
    "last_status": null,
    "last_error": null,
    "last_sent_at": null
  }
}

404 not_found:

not_found: لا يوجد هذا الرابط في حسابك.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

مثال — Unknown webhook endpoint

JSON · 404

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Link not found."
  }
}

422 validation_failed:

validation_failed: حقل خاطئ (بالقواعد نفسها عند الإنشاء).

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

مثال — Not https

JSON · 422

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "The URL must start with https://",
    "fields": {
      "url": [
        "The URL must start with https://"
      ]
    }
  }
}

401 مفتاح الـ API مفقود أو غير معروف. ردّ مشترك، انظر أدناه

أمثلة برمجية

curl

curl -X PATCH "https://YOUR_DOMAIN/api/v1/webhooks/7" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "active": true
}'

PHP

<?php
$ch = curl_init("https://YOUR_DOMAIN/api/v1/webhooks/7");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "PATCH",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("DS_API_KEY"),
        "Accept: application/json",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'active' => true,
    ]),
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!($body["success"] ?? false)) {
    throw new RuntimeException("$status {$body["error"]["code"]}: {$body["error"]["message"]}");
}
print_r($body["data"]);

JavaScript

const response = await fetch("https://YOUR_DOMAIN/api/v1/webhooks/7", {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${process.env.DS_API_KEY}`,
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "active": true
  }),
});
const json = await response.json();
if (!json.success) {
  throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
}
console.log(json.data);

Python

import os
import requests

response = requests.patch(
    "https://YOUR_DOMAIN/api/v1/webhooks/7",
    headers={
        "Authorization": f"Bearer {os.environ['DS_API_KEY']}",
        "Accept": "application/json",
    },
    json={
        "active": True,
    },
    timeout=30,
)
body = response.json()
if not body["success"]:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["data"])

الطريقة POST `/webhooks/{id}/test` #

إرسال رسالة اختبار

ترسل رسالة ping موقَّعة إلى الرابط وتبلغك بحالة HTTP التي ردّ بها نظامك. الاختبار الناجح يصفّر عدّاد الإخفاق. وهي محدودة بـ 10 طلبات في الدقيقة على مستوى المسار (نحو 5 عملياً، انظر ملاحظات حدود الطلبات).

الطلب POST /api/v1/webhooks/{id}/test
حدّ الطلبات في الدقيقة لكل عنوان IP 60 عاماً، و120 للواجهة كلها، و10 لهذا المسار
يتطلب ميزة الباقة: الـ API (تُفحص عندما تُطبَّق الباقات على حسابك)
أدلة الويب هوك الصادر: إشعارات فورية لنظامك التحقق من توقيع الويب هوك (X-DS-Signature)

معاملات المسار

الاسم النوع مطلوب الوصف

الاسم	النوع	مطلوب	الوصف
`id`	`integer`	مطلوب	معرّف رابط الويب هوك (من `GET /webhooks`). مثال `7`

id

integer

مطلوب

معرّف رابط الويب هوك (من GET /webhooks).

مثال 7

الردود

200 ردّ نظامك بحالة 2xx.

ردّ نظامك بحالة 2xx.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

الحقل	النوع	مطلوب	الوصف
`success`	`boolean`	مطلوب	قيمة ثابتة `true`
`data`	`object`	مطلوب	نتيجة رسالة اختبار ناجحة.
`delivered`	`boolean`	مطلوب	قيمة ثابتة `true`
`response_status`	`integer`	مطلوب	حالة HTTP التي ردّ بها نظامك.

مثال

JSON · 200

{
  "success": true,
  "data": {
    "delivered": true,
    "response_status": 200
  }
}

404 not_found:

not_found: لا يوجد هذا الرابط في حسابك.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

مثال — Unknown webhook endpoint

JSON · 404

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Link not found."
  }
}

422 delivery_failed:

delivery_failed: لم تصل الرسالة (ردّ غير 2xx أو تحويل أو انتهاء مهلة أو خطأ اتصال). يحمل response_status الحالة التي أعادها نظامك، أو null.

الترويسات: X-RateLimit-Limit X-RateLimit-Remaining

مثال — Your system refused

JSON · 422

{
  "success": false,
  "error": {
    "code": "delivery_failed",
    "message": "Not delivered: your system answered 500",
    "response_status": 500
  }
}