v1

Madar Merchant API

واجهة برمجية لربط نظام متجرك (موقعك، WooCommerce، Shopify، نظام نقاط البيع…) بمنصة مدار مباشرة: أنشئ طلبات التوصيل تلقائياً، واعرف المنطقة والرسوم قبل الإنشاء، وتابع الحالة، واستقبل إشعارات فورية عبر Webhooks عند كل تغيير — دون إدخال يدوي في البوابة.

Base URL

https://wasselni.naseir.site/api/v1

الصيغة

JSON (UTF-8) · أسماء الحقول camelCase

الأوقات

UTC دائماً بصيغة yyyy-MM-ddTHH:mm:ssZ

العملة

شيكل ILS — المبالغ أرقام عشرية برقمين

كل استجابة — نجاحاً أو فشلاً — تأتي بنفس الغلاف، وتحمل ترويسة X-Request-Id (نفس قيمة requestId) أرسلها للدعم عند أي مشكلة:

الـ API مخصّص للاتصال من خادم إلى خادم (server-to-server) عبر HTTPS فقط. يتوفر أيضاً توثيق Swagger التفاعلي وملف OpenAPI على /openapi/v1.json.

البدء السريع

1

سجّل متجرك من تسجيل متجر وانتظر تفعيل الحساب من الإدارة.

2

افتح صفحة «ربط API» من لوحة التاجر: /Merchant/ApiSettings.

3

ولّد مفتاح اختبار mk_test_… واحفظه فوراً في متغير بيئة على خادمك — يُعرض مرة واحدة فقط.

4

أنشئ طلباً تجريبياً عبر POST /orders — لا يصل لأي كابتن ولا يمسّ رصيدك.

5

حاكِ تغيّر الحالة عبر POST /orders/{idOrRef}/simulate واستقبل حدث order.status_changed على رابط الـ Webhook الذي سجّلته في «ربط API».

POST/orders

cURL

# 0) the test key from "ربط API" (server-side only)
export MADAR_API_KEY="mk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 1) check the key
curl https://wasselni.naseir.site/api/v1/me -H "X-Api-Key: $MADAR_API_KEY"

# 2) create a test order
curl -X POST https://wasselni.naseir.site/api/v1/orders \
  -H "X-Api-Key: $MADAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRef": "SHOP-10482",
    "recipientName": "محمد علي حسن",
    "recipientPhone": "0599301001",
    "address": "حي الرمال، شارع عمر المختار، غزة",
    "zone": "غزة",
    "paymentType": "cod",
    "codAmount": 80,
    "codCollectionTarget": "captain"
  }'
# => 201 { "success": true, "data": { "refNumber": "WP-20261024-4821", "livemode": false, ... } }

# 3) simulate the delivery flow (test keys only)
curl -X POST https://wasselni.naseir.site/api/v1/orders/WP-20261024-4821/simulate \
  -H "X-Api-Key: $MADAR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "status": "out_for_delivery" }'

curl -X POST https://wasselni.naseir.site/api/v1/orders/WP-20261024-4821/simulate \
  -H "X-Api-Key: $MADAR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "status": "delivered" }'
# => your webhook receives order.status_changed with "livemode": false

المصادقة

أرسل مفتاحك في الترويسة X-Api-Key مع كل طلب (ما عدا GET /health). لا تُقبل كوكيز تسجيل الدخول على /api، ولا يوجد تحويل لصفحة الدخول — الأخطاء دائماً JSON.

من خادمك فقط: لا تضع المفتاح أبداً في كود المتصفح أو تطبيق الجوال أو مستودع Git — احفظه في متغير بيئة (MADAR_API_KEY).
يُعرض مرة واحدة: نخزّن بصمة المفتاح فقط (SHA-256)، فلا يمكن استرجاعه لاحقاً؛ تظهر في البوابة بادئته فقط (مثل mk_live_7Hq2).
إعادة التوليد والإلغاء: من «ربط API» — إعادة التوليد تلغي المفتاح القديم فوراً وتُصدر جديداً؛ الإلغاء يوقف المفتاح نهائياً. الإدارة تستطيع إلغاء مفتاحك أيضاً.
HTTPS إلزامي: الطلب عبر HTTP يُرفض بـ 400 https_required بلا تحويل.

الحالة	HTTP	الكود
لا توجد ترويسة `X-Api-Key`	401	`missing_api_key`
مفتاح بشكل خاطئ أو غير موجود أو ملغى	401	`invalid_api_key`
حساب المتجر غير مفعّل أو موقوف	403	`merchant_not_active`
محاولات مصادقة فاشلة كثيرة من نفس الـ IP	429	`too_many_auth_failures`

GET/me

curl -X GET "https://wasselni.naseir.site/api/v1/me" \
  -H "X-Api-Key: $MADAR_API_KEY"

const res = await fetch("https://wasselni.naseir.site/api/v1/me", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.MADAR_API_KEY,
    "Content-Type": "application/json"
  }});
const body = await res.json();

$ch = curl_init("https://wasselni.naseir.site/api/v1/me");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: " . getenv("MADAR_API_KEY"),
    "Content-Type: application/json"
  ]]);
$body = json_decode(curl_exec($ch), true);

HTTP

GET /api/v1/me HTTP/1.1
Host: wasselni.naseir.site
X-Api-Key: mk_live_7Hq2xxxxxxxxxxxxxxxxxxxxxxxxxxxx

الوضع التجريبي (Sandbox)

لكل متجر نوعان من المفاتيح، ومفتاح فعّال واحد من كل نوع في الوقت نفسه. نوع المفتاح وحده يحدد الوضع — نفس الـ Base URL ونفس الـ endpoints.

Live

mk_live_…

طلبات حقيقية: تصل للإدارة والكباتن، تدخل رحلات الجمع والتوصيل، وتؤثر على رصيدك. "livemode": true.

Test

mk_test_…

طلبات تجريبية معزولة تماماً للتطوير والاختبار. "livemode": false.

عزل الطلبات التجريبية

لا تصل أبداً إلى الإدارة أو الكباتن، ولا تُنشئ رحلات جمع أو توصيل.
لا تؤثر على الرصيد إطلاقاً: GET /me/balance بمفتاح اختبار يُرجع رصيد 0 وبلا حركات.
كل استجابة طلب وكل payload لـ Webhook تحمل الحقل "livemode": false — تحقّق منه في نظامك قبل أي إجراء فعلي (شحن، فوترة…).
نفس externalRef يمكن أن يوجد مرة واحدة في كل وضع — طلب تجريبي SHOP-10482 لا يتعارض مع طلب حقيقي بنفس الرقم.
مفتاح الاختبار يرى الطلبات التجريبية فقط، ومفتاح الإنتاج يرى الحقيقية فقط.

محاكي الحالات POST `/orders/{idOrRef}/simulate`

المعاملات

الاسم	النوع	إلزامي	الوصف
`idOrRef`	string	نعم	معرّف الطلب التجريبي أو رقمه في المسار.
`status`	string	نعم	الحالة المطلوبة من القيم المبيّنة أدناه.

بما أن الطلب التجريبي لا يمر بكابتن، يمكنك تحريك حالته يدوياً لاختبار تكاملك وتلقّي Webhooks. المحاكي متاح أيضاً كأزرار في بوابة التاجر.

لمفاتيح الاختبار فقط — استدعاؤه بمفتاح mk_live_ يُرجع 403 test_mode_only.
الانتقال للأمام فقط ومن حالة غير نهائية — وإلا 409 invalid_transition (مثلاً محاكاة processing بعد out_for_delivery، أو أي محاكاة بعد delivered/returned/cancelled).
كل محاكاة ناجحة تُطلق حدث order.status_changed على الـ Webhook كأي تغيير حقيقي.

`status` المُرسَل	ما يراه التاجر `merchantStatus`	التسمية
`processing`	`processing`	قيد التجهيز
`out_for_delivery`	`out_for_delivery`	في الطريق
`delivered`	`delivered`	تم التسليم
`returned`	`returned`	مرتجع
`cancelled`	`cancelled`	ملغي

الاستجابة

بيانات الطلب التجريبي بعد الانتقال إلى الحالة المطلوبة.

الأخطاء

403 test_mode_only
409 invalid_transition
404 order_not_found

POST/orders/{idOrRef}/simulate

curl -X POST https://wasselni.naseir.site/api/v1/orders/WP-20261024-4821/simulate \
  -H "X-Api-Key: $MADAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "delivered" }'

const res = await fetch("https://wasselni.naseir.site/api/v1/orders/WP-20261024-4821/simulate", {
  method: "POST",
  headers: { "X-Api-Key": process.env.MADAR_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ status: "delivered" })
});
const body = await res.json();
if (!body.success) console.error(body.error.code); // test_mode_only | invalid_transition

$ch = curl_init("https://wasselni.naseir.site/api/v1/orders/WP-20261024-4821/simulate");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-Api-Key: " . getenv("MADAR_API_KEY"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["status" => "delivered"])]);
$body = json_decode(curl_exec($ch), true);

الاستجابة — حقول مختارة 200

{
  "success": true,
  "data": {
    "refNumber": "WP-20261024-4821",
    "status": "delivered",
    "merchantStatus": "delivered",
    "livemode": false
  },
  "error": null,
  "requestId": "sample-request-id"
}

الطلبات

الطريقة	المسار	الوصف
POST	`/orders`	إنشاء طلب
POST	`/orders/bulk`	إنشاء حتى 100 طلب دفعة واحدة
GET	`/orders/{idOrRef}`	طلب واحد مع سجل الحالات
GET	`/orders`	قائمة بفلاتر وتقسيم صفحات
POST	`/orders/{idOrRef}/cancel`	إلغاء طلب في حالة الانتظار
POST	`/orders/{idOrRef}/simulate`	محاكاة الحالة — مفاتيح الاختبار فقط (التفاصيل)

إنشاء طلب POST `/orders`

يُرجع 201 مع ترويسة Location: /api/v1/orders/{id} لطلب جديد، أو 200 عند إعادة إرسال نفس externalRef (منع التكرار). حد حجم الجسم 64KB.

المعاملات

الحقل	النوع	إلزامي	الوصف
`externalRef`	string	موصى به	رقم الطلب في نظامك — مفتاح منع التكرار ≤64، `[A-Za-z0-9_\-#./]`
`recipientName`	string	نعم	اسم المستلم 2–100 حرف
`recipientPhone`	string	نعم	جوال المستلم، مثال `0599123456` يُطبَّع (مسافات، `+970`/`+972`…) ثم `^05[69]\d{7}$`
`address`	string	نعم	العنوان الوصفي ≤300
`zone`	string	لا	المنطقة؛ إن غابت تُحسب من الموقع اسم منطقة موجودة (مطابقة تامة)
`latitude`	number	لا	خط العرض −90..90، مع `longitude` معاً
`longitude`	number	لا	خط الطول −180..180
`mapUrl`	string	لا	رابط واتساب / Google Maps ≤500؛ تُستخرج منه الإحداثيات إن غابت
`paymentType`	string	نعم	نوع التحصيل: الدفع عند الاستلام / مدفوع مسبقاً `cod` \| `prepaid`
`codAmount`	number	نعم	COD: قيمة الطلب التي تُحصَّل؛ Prepaid: قيمة إشارية لا تدخل الحسابات 0.01–99999
`deliveryFeeTarget`	string	لا	من يدفع رسوم التوصيل `merchant` (افتراضي) \| `customer`
`codCollectionTarget`	string	لا	من يستلم مبلغ COD — لـ COD فقط `wasselni_direct` (افتراضي) \| `captain` \| `merchant_pre_collected`
`notes`	string	لا	ملاحظات للكابتن ≤500

الاستجابة 201 Created:

totalCollect هو ما يجمعه الكابتن من الزبون: cod + رسوم على التاجر = codAmount؛ cod + رسوم على الزبون = codAmount + deliveryFee؛ prepaid + رسوم على الزبون = deliveryFee؛ prepaid + رسوم على التاجر = 0. تحذيرات غير قاتلة تظهر في meta.warnings: zone_mismatch، cod_collection_target_ignored، phone_normalized.

الاستجابة

طلب جديد مع معرّف ورقم تتبّع ورسوم التوصيل. عند التكرار تعاد بيانات الطلب الأصلي.

الأخطاء

422 validation_failed
422 zone_required
409 external_ref_conflict

POST/orders

curl -X POST https://wasselni.naseir.site/api/v1/orders \
  -H "X-Api-Key: $MADAR_API_KEY" -H "Content-Type: application/json" \
  -d '{"externalRef":"SHOP-10482","recipientName":"محمد علي","recipientPhone":"0599301001","address":"حي الرمال، غزة","latitude":31.5235,"longitude":34.4478,"paymentType":"cod","codAmount":80}'

const res = await fetch("https://wasselni.naseir.site/api/v1/orders", {
  method: "POST",
  headers: { "X-Api-Key": process.env.MADAR_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ externalRef: "SHOP-10482", recipientName: "محمد علي", recipientPhone: "0599301001",
                         address: "حي الرمال، غزة", zone: "غزة", paymentType: "prepaid", codAmount: 120 })
});
const body = await res.json();
if (!body.success) console.error(body.error.code, body.error.message);

$ch = curl_init("https://wasselni.naseir.site/api/v1/orders");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-Api-Key: " . getenv("MADAR_API_KEY"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["externalRef" => "SHOP-10482", "recipientName" => "محمد علي",
    "recipientPhone" => "0599301001", "address" => "حي الرمال، غزة", "mapUrl" => "https://maps.google.com/?q=31.5235,34.4478",
    "paymentType" => "cod", "codAmount" => 80], JSON_UNESCAPED_UNICODE)]);
$body = json_decode(curl_exec($ch), true);

الاستجابة 201

{
  "success": true,
  "data": {
    "id": "3f6d2a7e-0b51-4c1e-9b0e-7a2d9f1c4e88",
    "refNumber": "WP-20261022-4821",
    "externalRef": "SHOP-10482",
    "source": "api",
    "livemode": true,
    "status": "pending",
    "merchantStatus": "pending",
    "merchantStatusLabel": "انتظار",
    "recipientName": "محمد علي حسن",
    "recipientPhone": "0599301001",
    "address": "حي الرمال، شارع عمر المختار، بجانب البريد",
    "zone": "غزة",
    "latitude": 31.5235,
    "longitude": 34.4478,
    "paymentType": "cod",
    "codAmount": 80.00,
    "deliveryFeeTarget": "merchant",
    "codCollectionTarget": "captain",
    "deliveryFee": 5.00,
    "returnFee": 3.00,
    "totalCollect": 80.00,
    "currency": "ILS",
    "awaitingDirectTransfer": false,
    "notes": "الاتصال قبل التوصيل",
    "createdAt": "2026-10-22T09:15:04Z",
    "updatedAt": "2026-10-22T09:15:04Z",
    "trackingUrl": "https://wasselni.naseir.site/Track/Result?q=WP-20261022-4821"
  },
  "error": null,
  "meta": { "replayed": false, "warnings": [] },
  "requestId": "0HN7S1Q2K3L4M:00000001"
}

خيارات الدفع وأثرها المالي

cod + wasselni_direct الافتراضي

الزبون يحوّل قيمة الطلب مباشرة لحساب مدار. الطلب لا يُسلَّم حتى تؤكد الإدارة وصول التحويل (يظهر awaitingDirectTransfer: true حتى التأكيد). عند التسليم: رصيدك += codAmount، ثم −= deliveryFee إن كان deliveryFeeTarget=merchant.

cod + captain

الكابتن يقبض نقداً أو بتحويل لحسابه. عند التسليم: رصيدك += codAmount − deliveryFee (إن كانت عليك).

cod + merchant_pre_collected

قبضت المبلغ مسبقاً خارج المنصة. لا يُضاف codAmount لرصيدك؛ يُخصم deliveryFee فقط إن كانت عليك.

prepaid

codAmount قيمة إشارية فقط (الكابتن يُخبر الزبون بها) ولا تدخل أي حساب؛ عند التسليم يُخصم deliveryFee إن كانت عليك. codCollectionTarget يُتجاهل (تحذير cod_collection_target_ignored).

المرتجع (كل الأنواع)

يُخصم deliveryFee دائماً (بغض النظر عن deliveryFeeTarget) ويُخصم returnFee إن كان أكبر من صفر.

تحديد المنطقة

المنطقة تحدد رسوم التوصيل والمرتجع. ثلاث طرق، بالأولوية:

zone — اسم المنطقة كما يظهر في GET /zones (مطابقة تامة)؛ اسم غير موجود → 422 zone_not_found. إن أرسلت معه إحداثيات لمنطقة أخرى يُعتمد zone مع تحذير zone_mismatch.
latitude + longitude — تُكتشف المنطقة من حدودها المرسومة.
mapUrl — رابط خريطة (واتساب / Google Maps) تُستخرج منه الإحداثيات؛ إن تعذّر → 422 invalid_map_url.

لا منطقة ولا موقع → 422 zone_required. موقع خارج كل المناطق المرسومة → 422 zone_not_detected (أرسل zone صراحة). المناطق التي hasBoundary=false لا تُكتشف من الإحداثيات.

GET/zones

curl -X GET "https://wasselni.naseir.site/api/v1/zones" \
  -H "X-Api-Key: $MADAR_API_KEY"

const res = await fetch("https://wasselni.naseir.site/api/v1/zones", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.MADAR_API_KEY,
    "Content-Type": "application/json"
  }});
const body = await res.json();

$ch = curl_init("https://wasselni.naseir.site/api/v1/zones");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: " . getenv("MADAR_API_KEY"),
    "Content-Type: application/json"
  ]]);
$body = json_decode(curl_exec($ch), true);

الاستجابة 422

{ "success": false, "data": null,
  "error": { "code": "zone_not_detected", "message": "الموقع خارج كل مناطق التوصيل المرسومة — أرسل حقل zone صراحة",
             "details": { "latitude": 31.2001, "longitude": 34.2003 } },
  "requestId": "0HN7S1Q2K3L4M:00000002" }

منع التكرار بـ `externalRef`

أرسل رقم طلبك في externalRef. إعادة إرسال نفس القيمة (بعد انقطاع شبكة أو timeout) تُرجع الطلب الموجود بـ 200 وmeta.replayed=true وترويسة Idempotent-Replayed: true — دون إنشاء طلب ثانٍ.
المحتوى لا يُقارَن: الإعادة تُرجع الطلب الأصلي كما هو حتى لو اختلفت الحقول.
إن كان externalRef مستخدماً لطلب محذوف → 409 external_ref_conflict.
الفرادة لكل متجر ولكل وضع (live / test) على حدة.

جلب طلب GET `/orders/{idOrRef}`

المعاملات

الاسم	النوع	إلزامي	الوصف
`idOrRef`	string	نعم	معرّف UUID أو رقم الطلب في المسار.

idOrRef = المعرّف (uuid) أو refNumber (WP-…). يتضمن timeline من سجل الحالات تصاعدياً. طلب لمتجر آخر → 404 order_not_found. للبحث برقم طلبك استخدم GET /orders?externalRef=SHOP-10482.

الاستجابة

بيانات الطلب وسجل تغيّر الحالات في timeline.

الأخطاء

404 order_not_found

GET/orders/{idOrRef}

curl -X GET "https://wasselni.naseir.site/api/v1/orders/{idOrRef}" \
  -H "X-Api-Key: $MADAR_API_KEY"

const res = await fetch("https://wasselni.naseir.site/api/v1/orders/{idOrRef}", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.MADAR_API_KEY,
    "Content-Type": "application/json"
  }});
const body = await res.json();

$ch = curl_init("https://wasselni.naseir.site/api/v1/orders/{idOrRef}");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: " . getenv("MADAR_API_KEY"),
    "Content-Type: application/json"
  ]]);
$body = json_decode(curl_exec($ch), true);

الاستجابة 200

{ "success": true, "data": { "id": "3f6d2a7e-…", "refNumber": "WP-20261022-4821", "status": "at_warehouse", "merchantStatus": "processing", "merchantStatusLabel": "قيد التجهيز",
  "timeline": [ { "status": "pending", "merchantStatus": "pending", "at": "2026-10-22T09:15:04Z" },
                { "status": "collecting", "merchantStatus": "processing", "at": "2026-10-22T11:02:40Z" },
                { "status": "at_warehouse", "merchantStatus": "processing", "at": "2026-10-22T13:20:11Z" } ] }, "error": null, "requestId": "…" }

قائمة الطلبات GET `/orders`

Query	النوع	الوصف
`status`	string	مبسّطة، عدة قيم بفاصلة: `pending,processing,out_for_delivery,delivered,returned,cancelled`
`from`, `to`	ISO date / datetime UTC	على `createdAt`؛ `to` بتاريخ فقط يشمل اليوم كاملاً
`externalRef`	string	مطابقة تامة
`source`	string	`api` \| `portal` \| `app`
`page`	int ≥ 1	افتراضي 1
`pageSize`	int 1..100	افتراضي 20

ترتيب ثابت createdAt تنازلياً، بدون timeline. meta: page، pageSize، total، totalPages. قيمة غير صالحة (حالة غير معروفة، from > to، pageSize خارج النطاق) → 400 validation_failed.

الاستجابة

قائمة طلبات مع معلومات الصفحات في meta.

الأخطاء

400 validation_failed

GET/orders

curl -X GET "https://wasselni.naseir.site/api/v1/orders" \
  -H "X-Api-Key: $MADAR_API_KEY"

const res = await fetch("https://wasselni.naseir.site/api/v1/orders", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.MADAR_API_KEY,
    "Content-Type": "application/json"
  }});
const body = await res.json();

$ch = curl_init("https://wasselni.naseir.site/api/v1/orders");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: " . getenv("MADAR_API_KEY"),
    "Content-Type: application/json"
  ]]);
$body = json_decode(curl_exec($ch), true);

cURL

curl "https://wasselni.naseir.site/api/v1/orders?status=out_for_delivery,delivered&from=2026-10-01&to=2026-10-31&page=1&pageSize=50" \
  -H "X-Api-Key: $MADAR_API_KEY"

الاستجابة — قائمة فارغة 200

{
  "success": true,
  "data": [],
  "error": null,
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 0,
    "totalPages": 0
  },
  "requestId": "sample-request-id"
}

إلغاء طلب POST `/orders/{idOrRef}/cancel`

المعاملات

الاسم	النوع	إلزامي	الوصف
`idOrRef`	string	نعم	معرّف الطلب أو رقمه في المسار.
`reason`	string	لا	سبب الإلغاء، حتى 200 حرف.

مسموح للطلب في حالة pending فقط (قبل بدء رحلة الجمع).
جسم اختياري: { "reason": "الزبون ألغى" } (≤200 حرف).
ملغى مسبقاً → 200 مع meta.alreadyCancelled=true (آمن للإعادة).
أي حالة أخرى → 409 order_not_cancellable مع details.status؛ غير موجود → 404 order_not_found.

الاستجابة

بيانات الطلب بعد الإلغاء، مع meta.alreadyCancelled لتوضيح الإعادة.

الأخطاء

404 order_not_found
409 order_not_cancellable

POST/orders/{idOrRef}/cancel

curl -X POST "https://wasselni.naseir.site/api/v1/orders/{idOrRef}/cancel" \
  -H "X-Api-Key: $MADAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "الزبون ألغى" }'

const res = await fetch("https://wasselni.naseir.site/api/v1/orders/{idOrRef}/cancel", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.MADAR_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "reason": "الزبون ألغى" })});
const body = await res.json();

$ch = curl_init("https://wasselni.naseir.site/api/v1/orders/{idOrRef}/cancel");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: " . getenv("MADAR_API_KEY"),
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => '{ "reason": "الزبون ألغى" }']);
$body = json_decode(curl_exec($ch), true);

cURL

curl -X POST https://wasselni.naseir.site/api/v1/orders/WP-20261022-4821/cancel \
  -H "X-Api-Key: $MADAR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "reason": "الزبون ألغى" }'

الاستجابة — حقول مختارة 200

{
  "success": true,
  "data": {
    "refNumber": "WP-20261022-4821",
    "status": "cancelled",
    "merchantStatus": "cancelled"
  },
  "error": null,
  "meta": {
    "alreadyCancelled": false
  },
  "requestId": "sample-request-id"
}

إنشاء جماعي POST `/orders/bulk`

المعاملات

الاسم	النوع	إلزامي	الوصف
`orders`	array	نعم	من 1 إلى 100 عنصر، لكل عنصر معاملات إنشاء طلب.

الجسم { "orders": [ ... ] } من 1 إلى 100 طلب (وإلا 400 bulk_empty / 400 bulk_limit_exceeded)، وحد الحجم 1MB. كل عنصر يمر بنفس تحقق POST /orders ويُحفظ مستقلاً — نجاح جزئي ممكن: الرد 200 وsuccess=true ما دامت البنية صالحة حتى لو فشلت كل العناصر؛ المرجع هو summary.failed وresults[].error. مع externalRef تصبح إعادة إرسال الدفعة كاملة آمنة.

الاستجابة

ملخّص النتائج ونتيجة مستقلة لكل عنصر؛ قد تنجح بعض العناصر فقط.

الأخطاء

400 bulk_empty
400 bulk_limit_exceeded
413 payload_too_large

POST/orders/bulk

curl -X POST "https://wasselni.naseir.site/api/v1/orders/bulk" \
  -H "X-Api-Key: $MADAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "orders": [{ "externalRef": "SHOP-10483", "recipientName": "محمد علي", "recipientPhone": "0599301001", "address": "غزة", "zone": "غزة", "paymentType": "cod", "codAmount": 80 }] }'

const res = await fetch("https://wasselni.naseir.site/api/v1/orders/bulk", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.MADAR_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "orders": [{ "externalRef": "SHOP-10483", "recipientName": "محمد علي", "recipientPhone": "0599301001", "address": "غزة", "zone": "غزة", "paymentType": "cod", "codAmount": 80 }] })});
const body = await res.json();

$ch = curl_init("https://wasselni.naseir.site/api/v1/orders/bulk");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: " . getenv("MADAR_API_KEY"),
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => '{ "orders": [{ "externalRef": "SHOP-10483", "recipientName": "محمد علي", "recipientPhone": "0599301001", "address": "غزة", "zone": "غزة", "paymentType": "cod", "codAmount": 80 }] }']);
$body = json_decode(curl_exec($ch), true);

الاستجابة 200

{ "success": true,
  "data": {
    "summary": { "total": 3, "created": 1, "replayed": 1, "failed": 1 },
    "results": [
      { "index": 0, "externalRef": "SHOP-10483", "success": true, "replayed": false, "order": { "id": "…", "refNumber": "WP-20261022-5170", "zone": "جباليا", "deliveryFee": 6.00, "totalCollect": 45.00, "merchantStatus": "pending" } },
      { "index": 1, "externalRef": "SHOP-10482", "success": true, "replayed": true,  "order": { "id": "3f6d2a7e-…", "refNumber": "WP-20261022-4821" } },
      { "index": 2, "externalRef": "SHOP-10484", "success": false, "error": { "code": "zone_not_detected", "message": "الموقع خارج كل مناطق التوصيل المرسومة" } }
    ] },
  "error": null, "requestId": "…" }

المناطق والرسوم

GET `/zones`

name هو القيمة التي تُرسل في حقل zone. أضف ?includeBoundary=true لإرفاق حدود GeoJSON Polygon ([lng, lat]) للمناطق المرسومة.

المعاملات

الاسم	النوع	إلزامي	الوصف
`includeBoundary`	boolean	لا	إرفاق حدود المناطق بصيغة GeoJSON عند true؛ الافتراضي false.

الاستجابة

قائمة المناطق مع رسوم التوصيل والمرتجع ووجود الحدود.

الأخطاء

401 invalid_api_key

GET/zones

curl -X GET "https://wasselni.naseir.site/api/v1/zones" \
  -H "X-Api-Key: $MADAR_API_KEY"

const res = await fetch("https://wasselni.naseir.site/api/v1/zones", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.MADAR_API_KEY,
    "Content-Type": "application/json"
  }});
const body = await res.json();

$ch = curl_init("https://wasselni.naseir.site/api/v1/zones");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: " . getenv("MADAR_API_KEY"),
    "Content-Type: application/json"
  ]]);
$body = json_decode(curl_exec($ch), true);

الاستجابة 200

{ "success": true, "data": [
  { "name": "النصيرات", "deliveryFee": 7.00, "returnFee": 4.00, "hasBoundary": false },
  { "name": "جباليا",   "deliveryFee": 6.00, "returnFee": 3.00, "hasBoundary": false },
  { "name": "خانيونس",  "deliveryFee": 7.00, "returnFee": 4.00, "hasBoundary": false },
  { "name": "غزة",      "deliveryFee": 5.00, "returnFee": 3.00, "hasBoundary": true, "boundary": {"type":"Polygon","coordinates":[[[34.44,31.54],[34.49,31.54],[34.49,31.49],[34.44,31.49],[34.44,31.54]]]} }
], "error": null, "requestId": "…" }

GET `/zones/detect?lat=…&lng=…`

نفس خوارزمية الإنشاء — لعرض الرسوم في صفحة الدفع عندك قبل إنشاء الطلب. إحداثيات غير صالحة → 400 validation_failed؛ خارج كل المناطق → 422 zone_not_detected.

المعاملات

الاسم	النوع	إلزامي	الوصف
`lat`	number	نعم	خط العرض بين −90 و90.
`lng`	number	نعم	خط الطول بين −180 و180.

الاستجابة

المنطقة المطابقة ورسوم التوصيل والمرتجع.

الأخطاء

400 validation_failed
422 zone_not_detected

GET/zones/detect?lat=…&lng=…

curl -X GET "https://wasselni.naseir.site/api/v1/zones/detect?lat=31.5235&lng=34.4478" \
  -H "X-Api-Key: $MADAR_API_KEY"

const res = await fetch("https://wasselni.naseir.site/api/v1/zones/detect?lat=31.5235&lng=34.4478", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.MADAR_API_KEY,
    "Content-Type": "application/json"
  }});
const body = await res.json();

$ch = curl_init("https://wasselni.naseir.site/api/v1/zones/detect?lat=31.5235&lng=34.4478");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: " . getenv("MADAR_API_KEY"),
    "Content-Type: application/json"
  ]]);
$body = json_decode(curl_exec($ch), true);

cURL

curl "https://wasselni.naseir.site/api/v1/zones/detect?lat=31.5235&lng=34.4478" -H "X-Api-Key: $MADAR_API_KEY"
# => { "success": true, "data": { "zone": "غزة", "deliveryFee": 5.00, "returnFee": 3.00 }, ... }

الاستجابة 200

{
  "success": true,
  "data": { "zone": "غزة", "deliveryFee": 5.00, "returnFee": 3.00 },
  "error": null,
  "requestId": "sample-request-id"
}

الحساب

GET `/me`

ملف المتجر + المفتاح المستخدم (البادئة فقط) + حالة الـ Webhook. مناسب كأول طلب لاختبار المفتاح. بمفتاح اختبار: livemode=false وbalance = 0.

المعاملات

لا توجد معاملات؛ أرسل ترويسة المصادقة فقط.

الاستجابة

ملف المتجر والمفتاح المستخدم وحالة ربط Webhook والوضع الفعّال.

الأخطاء

401 invalid_api_key
403 merchant_not_active

GET/me

curl -X GET "https://wasselni.naseir.site/api/v1/me" \
  -H "X-Api-Key: $MADAR_API_KEY"

const res = await fetch("https://wasselni.naseir.site/api/v1/me", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.MADAR_API_KEY,
    "Content-Type": "application/json"
  }});
const body = await res.json();

$ch = curl_init("https://wasselni.naseir.site/api/v1/me");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: " . getenv("MADAR_API_KEY"),
    "Content-Type: application/json"
  ]]);
$body = json_decode(curl_exec($ch), true);

الاستجابة 200

{ "success": true, "data": {
  "merchantId": "8c1e…", "storeName": "مطبعة شهد", "email": "shahd@print.ps", "phone": "0599-200-100",
  "zone": "غزة", "status": "active", "balance": 140.00, "currency": "ILS",
  "apiKey": { "prefix": "mk_live_7Hq2", "createdAt": "2026-10-22T08:00:00Z", "lastUsedAt": "2026-10-22T09:15:04Z" },
  "webhook": { "configured": true, "url": "https://shop.example.ps/madar/webhook", "isActive": true, "events": ["order.created","order.status_changed"] },
  "livemode": true
}, "error": null, "requestId": "…" }

GET `/me/balance?limit=20`

الرصيد وآخر الحركات (limit من 1 إلى 100، افتراضي 20). type: cod_credit، delivery_fee، return_fee، withdrawal، adjustment؛ amount بإشارته (الخصومات سالبة). بمفتاح اختبار: رصيد 0 وبلا حركات.

المعاملات

الاسم	النوع	إلزامي	الوصف
`limit`	integer	لا	عدد الحركات، من 1 إلى 100؛ الافتراضي 20.

الاستجابة

الرصيد والعملة وآخر الحركات؛ الوضع التجريبي يعيد صفراً بلا حركات.

الأخطاء

400 validation_failed
401 invalid_api_key

GET/me/balance?limit=20

curl -X GET "https://wasselni.naseir.site/api/v1/me/balance?limit=20" \
  -H "X-Api-Key: $MADAR_API_KEY"

const res = await fetch("https://wasselni.naseir.site/api/v1/me/balance?limit=20", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.MADAR_API_KEY,
    "Content-Type": "application/json"
  }});
const body = await res.json();

$ch = curl_init("https://wasselni.naseir.site/api/v1/me/balance?limit=20");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: " . getenv("MADAR_API_KEY"),
    "Content-Type: application/json"
  ]]);
$body = json_decode(curl_exec($ch), true);

الاستجابة 200

{ "success": true, "data": {
  "balance": 140.00, "currency": "ILS", "hasPendingWithdrawal": false,
  "transactions": [
    { "type": "delivery_fee", "amount": -5.00, "description": "رسوم توصيل — WP-20261022-4821", "orderRefNumber": "WP-20261022-4821", "createdAt": "2026-10-22T16:40:00Z" },
    { "type": "cod_credit",   "amount": 80.00, "description": "تحصيل COD — WP-20261022-4821", "orderRefNumber": "WP-20261022-4821", "createdAt": "2026-10-22T16:40:00Z" }
  ] }, "error": null, "requestId": "…" }

Webhooks

سجّل رابط HTTPS واحداً من «ربط API» واحفظ السر whsec_… (يُعرض مرة واحدة). نرسل POST بجسم JSON موقّع عند كل حدث، ويمكنك إرسال حدث تجريبي من زر «اختبار» أو عبر POST /webhooks/test (بلا جسم، حد 5 طلبات/دقيقة؛ 422 webhook_not_configured / webhook_disabled).

الحدث	متى	`data`
`order.created`	إنشاء طلب (من الـ API أو البوابة)	`order` مع `change: null`
`order.status_changed`	كل تغيير حالة (حقيقي أو عبر المحاكي)	`order` + `change`
`webhook.test`	زر «اختبار» أو `POST /webhooks/test`	`{ "message": "اختبار من مدار" }`

الترويسات والـ Payload

الترويسة	المعنى
`X-Madar-Signature`	`t=<unix>,v1=<hex>` — HMAC-SHA256 للنص `"{t}.{rawBody}"` بسر الـ Webhook
`X-Madar-Event`	نوع الحدث
`X-Madar-Event-Id`	معرّف الحدث (= `id` في الجسم) — ثابت عبر إعادات المحاولة: استخدمه لتجاهل التكرار
`X-Madar-Delivery`	معرّف محاولة التسليم هذه

HTTP

POST https://shop.example.ps/madar/webhook
Content-Type: application/json; charset=utf-8
User-Agent: Madar-Webhooks/1.0
X-Madar-Event: order.status_changed
X-Madar-Event-Id: 9b2f0c1e-6a41-4d6e-8f0d-2c7b1e5a9d33
X-Madar-Delivery: 1d7e5c22-0f3a-4b8e-a6c1-5e9d2b7f4a10
X-Madar-Signature: t=1792660800,v1=5f2c8e0b4a...e91d

{
  "id": "9b2f0c1e-6a41-4d6e-8f0d-2c7b1e5a9d33",
  "type": "order.status_changed",
  "apiVersion": "v1",
  "livemode": true,
  "occurredAt": "2026-10-22T16:40:00Z",
  "data": {
    "order": {
      "id": "3f6d2a7e-0b51-4c1e-9b0e-7a2d9f1c4e88",
      "refNumber": "WP-20261022-4821",
      "externalRef": "SHOP-10482",
      "status": "delivered",
      "merchantStatus": "delivered",
      "merchantStatusLabel": "تم التسليم",
      "zone": "غزة",
      "paymentType": "cod",
      "codAmount": 80.00,
      "deliveryFee": 5.00,
      "returnFee": 3.00,
      "totalCollect": 80.00,
      "codCollectionTarget": "captain",
      "updatedAt": "2026-10-22T16:40:00Z",
      "trackingUrl": "https://wasselni.naseir.site/Track/Result?q=WP-20261022-4821"
    },
    "change": {
      "previousStatus": "out_for_delivery",
      "previousMerchantStatus": "out_for_delivery",
      "merchantStatusChanged": true
    }
  }
}

التحقق من التوقيع

احسب HMAC على الجسم الخام كما وصل (قبل أي JSON parse)، وقارن بمقارنة ثابتة الزمن، وارفض أي t أبعد من 5 دقائق عن وقتك (حماية من إعادة الإرسال). الترويسة قد تحمل أكثر من v1 عند تدوير السر — يكفي تطابق واحد.

// Node.js / Express — verify against the RAW body
const crypto = require("crypto");
const express = require("express");
const app = express();

function verifyMadarSignature(rawBody, header, secret, toleranceSec = 300) {
  if (!header) return false;
  let t = null; const sigs = [];
  for (const part of header.split(",")) {
    const i = part.indexOf("=");
    const k = part.slice(0, i).trim(), v = part.slice(i + 1).trim();
    if (k === "t") t = v; else if (k === "v1") sigs.push(v);
  }
  if (!/^\d+$/.test(t || "") || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const expected = Buffer.from(
    crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"), "utf8");
  return sigs.some(s => {
    const got = Buffer.from(s, "utf8");
    return got.length === expected.length && crypto.timingSafeEqual(got, expected);
  });
}

app.post("/madar/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verifyMadarSignature(raw, req.get("X-Madar-Signature"), process.env.MADAR_WEBHOOK_SECRET))
    return res.status(400).send("invalid signature");

  const eventId = req.get("X-Madar-Event-Id");   // dedupe: skip if already processed
  const event = JSON.parse(raw);
  if (event.livemode === false) { /* test order — never ship */ }

  res.sendStatus(200);                           // reply 2xx fast (< 10s) ...
  setImmediate(() => handleEvent(eventId, event)); // ... then process
});

<?php
$secret = getenv('MADAR_WEBHOOK_SECRET');
$raw    = file_get_contents('php://input');           // RAW body
$header = $_SERVER['HTTP_X_MADAR_SIGNATURE'] ?? '';

$t = null; $sigs = [];
foreach (explode(',', $header) as $part) {
    [$k, $v] = array_pad(explode('=', trim($part), 2), 2, '');
    if ($k === 't') $t = $v; elseif ($k === 'v1') $sigs[] = $v;
}

$ok = false;
if ($t !== null && ctype_digit($t) && abs(time() - (int)$t) <= 300) {
    $expected = hash_hmac('sha256', $t . '.' . $raw, $secret);
    foreach ($sigs as $s) { if (hash_equals($expected, $s)) { $ok = true; } }  // timing-safe
}
if (!$ok) { http_response_code(400); exit('invalid signature'); }

$eventId = $_SERVER['HTTP_X_MADAR_EVENT_ID'] ?? '';    // dedupe by this id
$event   = json_decode($raw, true);
if (($event['livemode'] ?? true) === false) { /* test order — never ship */ }

http_response_code(200);                              // reply 2xx within 10s

التسليم وإعادة المحاولة

ردّ بـ 2xx خلال 10 ثوانٍ — أي كود آخر أو انقطاع أو تجاوز المهلة يُعدّ فشلاً. استلم وأكّد سريعاً ثم عالج في الخلفية.
جدول إعادة المحاولة بعد الفشل: 1 دقيقة 5 دقائق 30 دقيقة 2 ساعة 12 ساعة ← متوقف (6 محاولات كحد أقصى). يمكنك «إعادة الإرسال» يدوياً من سجل التسليم في البوابة.
إيقاف تلقائي: بعد 25 فشلاً متتالياً يُعطَّل الـ Webhook — أصلح الرابط ثم فعّله من «ربط API».
قد يصل الحدث أكثر من مرة (إعادة محاولة أو إعادة إرسال يدوية) وقد لا يصل بالترتيب — تجاهل التكرار بـ X-Madar-Event-Id، واعتمد occurredAt أو GET /orders/{idOrRef} للحالة النهائية.
الرابط يجب أن يكون HTTPS عاماً — العناوين الخاصة/الداخلية مرفوضة ولا تُتبع التحويلات (redirects).

الحالات

كل طلب يحمل status (الحالة التشغيلية الداخلية) وmerchantStatus (الحالة المبسّطة التي يراها التاجر) وmerchantStatusLabel (التسمية العربية). ننصح ببناء منطقك على merchantStatus — قيمه ثابتة ولن تتغير. المسار: pending ← collecting ← at_warehouse ← out_for_delivery ← delivered / returned.

الحالة الداخلية `status`	`merchantStatus`	ما يراه المتجر
`pending`	`pending`	انتظار
`collecting` / `at_warehouse` / `assigned`	`processing`	قيد التجهيز
`out_for_delivery`	`out_for_delivery`	في الطريق
`delivered`	`delivered`	تم التسليم
`returned`	`returned`	مرتجع
`cancelled`	`cancelled`	ملغي

الحالات delivered وreturned وcancelled نهائية لا تتغير. القيمة الاحتياطية settled تُعرض للتاجر كـ delivered.

الأخطاء

عند الفشل: success=false وdata=null وerror يحمل code (ثابت بصيغة snake_case — ابنِ منطقك عليه) وmessage (عربي للعرض، قد يتغير) وdetails اختيارية. أخطاء التحقق تُفصّل في details.fields[]. لا تظهر أي تفاصيل داخلية — أرسل requestId للدعم.

HTTP	`code`	الرسالة
400	`https_required`	يجب استخدام HTTPS
400	`invalid_json`	جسم الطلب ليس JSON صالحاً
400	`validation_failed`	بيانات غير صالحة
400	`bulk_empty`	قائمة الطلبات فارغة
400	`bulk_limit_exceeded`	الحد الأقصى 100 طلب في الدفعة
401	`missing_api_key`	مفتاح API مفقود — أرسل ترويسة X-Api-Key
401	`invalid_api_key`	مفتاح API غير صالح أو ملغى
403	`merchant_not_active`	حساب المتجر غير مفعّل أو موقوف
403	`test_mode_only`	هذه العملية متاحة في الوضع التجريبي فقط
404	`order_not_found`	الطلب غير موجود
404	`not_found`	المسار غير موجود
405	`method_not_allowed`	طريقة HTTP غير مسموحة لهذا المسار
409	`order_not_cancellable`	لا يمكن إلغاء الطلب بعد بدء رحلة الجمع
409	`external_ref_conflict`	رقم الطلب الخارجي مستخدم لطلب محذوف
409	`invalid_transition`	لا يمكن نقل الطلب إلى هذه الحالة
413	`payload_too_large`	حجم الطلب أكبر من المسموح
422	`zone_required`	حدّد المنطقة أو أرسل الموقع
422	`zone_not_found`	المنطقة غير موجودة — راجع GET /zones
422	`zone_not_detected`	الموقع خارج كل مناطق التوصيل المرسومة — أرسل حقل zone صراحة
422	`invalid_map_url`	تعذّر استخراج الإحداثيات من رابط الخريطة
422	`invalid_phone`	رقم الجوال غير صالح — مثال: 0599123456
422	`webhook_not_configured`	لم يُضبط رابط Webhook بعد
422	`webhook_disabled`	الـ Webhook معطّل — فعّله من البوابة
429	`too_many_auth_failures`	محاولات مصادقة فاشلة كثيرة — حاول لاحقاً
429	`rate_limited`	تجاوزت الحد المسموح من الطلبات — حاول بعد قليل
500	`internal_error`	خطأ داخلي — أرسل requestId للدعم
503	`service_unavailable`	الخدمة غير متاحة مؤقتاً

الحدود

الحد	القيمة	عند التجاوز
لكل مفتاح API	120 طلب / دقيقة	`429 rate_limited`
لكل عنوان IP (كل `/api`)	300 طلب / دقيقة	`429 rate_limited`
محاولات مصادقة فاشلة لكل IP	20 خلال 5 دقائق	`429 too_many_auth_failures`
POST `/webhooks/test`	5 طلبات / دقيقة	`429 rate_limited`
حجم الجسم	64KB	`413 payload_too_large`
حجم جسم `POST /orders/bulk`	1MB، حتى 100 طلب	`413 payload_too_large` / `400 bulk_limit_exceeded`
`pageSize` في القوائم	1..100	`400 validation_failed`

ردود 429 تحمل ترويسة Retry-After بالثواني — انتظرها قبل الإعادة، ويُفضّل استخدام تراجع أُسّي (exponential backoff) مع الأخطاء 5xx.

سجل التغييرات

v1

الإصدار الأول 2026-10-24

إنشاء الطلبات (فردي وجماعي حتى 100) مع منع التكرار بـ externalRef واكتشاف المنطقة من الموقع، جلب/قائمة/إلغاء الطلبات، المناطق والرسوم، الحساب والرصيد، Webhooks موقّعة مع إعادة المحاولة، والوضع التجريبي بمفاتيح mk_test_ ومحاكي الحالات.

Madar Merchant API

البدء السريع

المصادقة

الوضع التجريبي (Sandbox)

عزل الطلبات التجريبية

محاكي الحالات POST /orders/{idOrRef}/simulate

المعاملات

الاستجابة

الأخطاء

الطلبات

إنشاء طلب POST /orders

المعاملات

الاستجابة

الأخطاء

خيارات الدفع وأثرها المالي

تحديد المنطقة

منع التكرار بـ externalRef

جلب طلب GET /orders/{idOrRef}

المعاملات

الاستجابة

الأخطاء

قائمة الطلبات GET /orders

الاستجابة

الأخطاء

إلغاء طلب POST /orders/{idOrRef}/cancel

المعاملات

الاستجابة

الأخطاء

إنشاء جماعي POST /orders/bulk

المعاملات

الاستجابة

الأخطاء

المناطق والرسوم

GET /zones

المعاملات

الاستجابة

الأخطاء

GET /zones/detect?lat=…&lng=…

المعاملات

الاستجابة

الأخطاء

الحساب

GET /me

المعاملات

الاستجابة

الأخطاء

GET /me/balance?limit=20

المعاملات

الاستجابة

الأخطاء

Webhooks

الترويسات والـ Payload

التحقق من التوقيع

التسليم وإعادة المحاولة

الحالات

الأخطاء

الحدود

سجل التغييرات

محاكي الحالات POST `/orders/{idOrRef}/simulate`

إنشاء طلب POST `/orders`

منع التكرار بـ `externalRef`

جلب طلب GET `/orders/{idOrRef}`

قائمة الطلبات GET `/orders`

إلغاء طلب POST `/orders/{idOrRef}/cancel`

إنشاء جماعي POST `/orders/bulk`

GET `/zones`

GET `/zones/detect?lat=…&lng=…`

GET `/me`

GET `/me/balance?limit=20`