شرحُ هذه الصفحة بالعربيّة، والمواصفةُ الملزمة هي ملفُّ openapi.yaml بالإنجليزيّة. لأيِّ سؤالٍ تواصل معنا.

للمطوّرين — واجهة زاد جو البرمجيّة للتجّار

اربط نظامَ مطعمك (نقطةَ البيع أو نظامَ القوائم) بزاد جو مباشرة: حالةُ متجرك، قائمتُك، دورةُ الطلب من جهتك، وأحداثٌ تصلك لحظةَ وقوعها — بمفتاحٍ لكلِّ مطعم.

🛠️ الحالة: المواصفة ١.٠ معتمدة، والخادم قيد البناء. لا نَعِد بنقطةٍ لم تُنشر — حين تفتح بيئةُ التجربة تُذكر هنا بتاريخها، وتُطلب مفاتيحُ التجربة من info@zadgo.com. المواصفةُ الكاملة بصيغة OpenAPI: openapi.yaml.

المبادئ التي لا تتغيّر

مفتاحٌ لكلِّ مطعم لا لكلِّ حساب — يُصدره مديرُ زاد جو من لوحته ويُعرض مرّةً واحدة، ويُلغى من اللوحة نفسِها.
الواجهةُ لا تمسّ مالاً: لا تعديلَ لعمولةٍ ولا رسوم — الطلبُ يُقبل ويُرفض ويُعلَن جاهزاً، ولا يُسعَّر.
كلُّ كتابةٍ بمفتاح تكرار (Idempotency-Key): الشبكةُ تعيد الإرسال، والطلبُ نفسُه لا يُنفَّذ مرّتين.
الأحداثُ موقَّعة (HMAC-SHA256 بسرِّ متجرك) — ومستقبلُك يتحقّق قبل أن يصدّق.
الحدودُ تُعلَن في الردّ (X-RateLimit-*) لا تُكتشف بالخطأ.

المصادقة

كلُّ طلبٍ يحمل الترويسة X-ZadGo-Key. المفتاحُ يُطابَق بتجزئته على الخادم ولا يُخزَّن نصّاً.

GET /v1/store HTTP/1.1
Host: api.zadgo.co
X-ZadGo-Key: zg_live_…

الموارد

🏪 المتجر

GET/v1/store PATCH/v1/store — فتحٌ/إغلاق · pauseMinutes (مشغولٌ مدّةً ثمّ يعود وحده) · ساعاتُ العمل · سقفُ الطلبات الجارية · الحدُّ الأدنى

🍔 القائمة

GET/v1/menu PUT/v1/menu — مزامنةٌ كاملة بمعرّفاتك (externalId): الغائبُ يُطفأ ولا يُحذف PATCH/v1/menu/items/{itemId} — التوفّرُ · نفد حتى · السعرُ · العرضُ (بحدود قاعدة العروض)

🧾 الطلبات

GET/v1/orders?status=pending — ما ينتظر قبولك GET/v1/orders/{orderId} POST/v1/orders/{orderId}/accept — مع prepMinutes POST/v1/orders/{orderId}/reject — بسببٍ من قائمةٍ مغلقة يصل العميل POST/v1/orders/{orderId}/ready

🔔 الويب هوك

GET/v1/webhooks POST/v1/webhooks — رابطُ https وقائمةُ أحداث؛ يُختبر بـping قبل القبول DELETE/v1/webhooks/{id}

الحدث	متى
`order.created`	طلبٌ جديدٌ ينتظر قبولك
`order.status_changed`	كلُّ انتقال حالة (أُسند · استُلم · في الطريق · سُلِّم)
`order.cancelled`	ألغاه العميلُ أو النظام — مع السبب إن وُجد
`menu.item_disabled`	أُطفئ صنفٌ من لوحة زاد جو أو التطبيق
`settlement.created`	صدرت تسويةٌ لمتجرك (بلا أرقام عمولة — الكشفُ في لوحتك)

POST https://your-server/zadgo HTTP/1.1
X-ZadGo-Delivery: dlv_01J…
X-ZadGo-Signature: sha256=3f9a…
Content-Type: application/json

{"id":"dlv_01J…","type":"order.created","at":"2026-10-01T12:03:44Z",
 "data":{"orderId":"…","orderNumber":"1042","items":[…],"paymentMethod":"cash"}}

التحقّق: HMAC_SHA256(الجسم الخام، السرّ) ثمّ قارِن بالترويسة. المعرّفُ X-ZadGo-Delivery فريد — تجاهل المكرَّر. إعادةُ المحاولة بتراجعٍ أُسّيٍّ لساعة، ويُعطَّل الاشتراك بعد ٥٠ فشلاً متتالياً ويُبلَّغ صاحبُه.

الأخطاء

الرمز	المعنى
`401 invalid_key`	المفتاحُ غيرُ صالحٍ أو أُلغي
`409 order_not_pending`	الطلبُ ليس بانتظارك (قُبل أو أُلغي)
`422 offer_above_price`	سعرُ العرض ليس أقلَّ من السعر
`429 rate_limited`	تجاوزتَ الحدّ — انتظر ما تقوله `Retry-After`

كلُّ خطأٍ جسمُه {"code","message"} والرسالةُ بالعربيّة.

بيئةُ التجربة

https://sandbox.api.zadgo.co/v1 — طلباتٌ مصنوعة تصل كلَّ بضع دقائق، ولا كباتنَ حقيقيّين. مفتاحُ التجربة يبدأ بـzg_test_. حين تفتح تُذكر هنا بتاريخها.