الربط والمطورون

اربط نظامك الخاص: واجهة الطلبات وخطافات الويب

لمن: المالكون، العمليات أين تجدها: الإعداد > التكاملات > خطافات الويب، مفاتيح API متاحة في: لوحة التحكم على الويب · كل الدول هذا الدليل للمطور الذي يربط نظام المطعم الخاص بزيدا، كنظام ERP أو نظام نقاط بيع أو أداة جداول. ويشرح الاتجاهين: زيدا ترسل الطلبات إلى نظامك، ونظامك يرسل الطلبات إلى زيدا. كيف يعمل - خطافات الويب (من زيدا إلى نظامك). ترسل إليك زيدا طلب HTTP كلما تغير طلب من طلبات المتجر. - واجهة الطلبات (من نظامك إلى زيدا). ترسل أنت إلى زيدا الطلبات التي أخذها المتجر خارج زيدا، كالتي جاءت من تطبيق توصيل أو بالهاتف. تستطيع أن تستعمل اتجاهًا واحدًا أو الاتجاهين. ويعدهما في لوحة التحكم من يستطيع فتح الإعداد > التكاملات في المتجر. اقرأ أعد خطافات الويب ومفاتيح API. وكل الأمثلة في هذه الصفحة مختلقة، فليس فيها مفتاح ولا سر ولا متجر ولا عميل حقيقي. صفحة مفاتيح API، وفيها العنوان الذي يرسل إليه نظامك الطلبات لخطافات الويب، التي ترسل طلبات زيدا إلى نظامك فور حدوثها، دليل خاص بها: استقبل طلبات زيدا عبر خطاف الويب. احصل على مفتاح API 1. افتح الإعداد > التكاملات > مفاتيح API في لوحة تحكم زيدا. 2. اضغط إنشاء مفتاح، ثم إنشاء. 3. انسخ المفتاح. ولا تعرضه زيدا إلا مرة واحدة، فاحفظه على خادمك وحده. أول المفتاح zyda_sk_. والمفتاح يدل على المتجر، فلا ترسل معرف المتجر أبدًا. ويستطيع المتجر أن يبطل المفتاح متى شاء. وللمتجر 10 مفاتيح نشطة على الأكثر. أرسل طلبًا POST https://dashboard.zyda.com/api/v1/stores/orders Authorization: Bearer <key> Content-Type: application/json - أرسل طلبًا واحدًا في كل استدعاء، على شكل كائن JSON. - لا يزيد المحتوى على 256 KB. - لا يرسل المفتاح الواحد أكثر من 120 استدعاء في الدقيقة. فإن زاد، جاء الرد 429 ومعه ترويسة Retry-After بالثواني. وما تفعله زيدا بالطلب يتبع قيمة status: - completed أو canceled: بيع مسجل. تحفظ زيدا البيع ولا شيء غير ذلك: لا رسالة إلى العميل، ولا تذكرة للمطبخ، ولا إرسال إلى نظام نقاط البيع، ولا حدث خطاف ويب. - placed: طلب حي. الطلب ما زال مفتوحًا. فيذهب إلى الطلبات الحالية في المتجر، وينقله فريق المتجر بين حالاته. ولا يعمل هذا إلا لمصدر طلب فعل فيه المتجر إظهار في الطلبات الحالية. انظر «الطلبات الحية». حقول الطلب الحقول الموسومة مطلوب يجب أن تحضر وألا تكون فارغة. وتتجاهل زيدا كل حقل لا تذكره هذه الصفحة. | الحقل | النوع | مطلوب | ملاحظات | |---|---|---|---| | branch_id | integer | مطلوب | معرف الفرع في زيدا. ويجب أن يكون فرعًا من فروع المتجر صاحب المفتاح. | | channel | string | مطلوب | مصدر الطلب، وهو أحد المفاتيح في «مصادر الطلبات» أدناه. ويجب أن يكون المتجر قد فعله. | | external_order_id | string | مطلوب | معرف الطلب عندك. 128 حرفًا على الأكثر. ولا تفرق زيدا بين الحروف الكبيرة والصغيرة، فـ ERP-1 وerp-1 طلب واحد. | | placed_at | string | مطلوب | وقت طلب العميل، بصيغة ISO 8601 مع المنطقة الزمنية، مثل 2026-10-14T13:05:00+03:00. ولا يتقدم على الوقت الحالي أكثر من 10 دقائق. | | status | string | مطلوب | completed أو canceled أو placed. | | total | number | مطلوب | ما دفعه العميل كله. انظر «المبالغ». | | currency | string | مطلوب | رمز عملة المتجر، مثل KWD أو EGP. وترفض زيدا أي عملة غيرها. | | subtotal | number | اختياري | انظر «المبالغ». | | discount | number | اختياري | انظر «المبالغ». | | delivery_fee | number | اختياري | انظر «المبالغ». | | tax | number | اختياري | انظر «المبالغ». | | delivery_type | string | اختياري | delivery أو pickup أو dine_in. | | payment_method | string | اختياري | cash أو card_on_delivery أو prepaid. | | notes | string | اختياري | نص حر، 2000 حرف على الأكثر. وفي الطلب الحي يرى فريق المتجر أول 1000 حرف منه ملاحظة على الطلب. ولا يراه العميل أبدًا. | | customer | object | اختياري | انظر «كائن العميل». وتقبل زيدا null. | | items | array | اختياري | أسطر الطلب، 200 سطر على الأكثر. انظر «كائن الصنف». | كائن العميل | الحقل | النوع | مطلوب | ملاحظات | |---|---|---|---| | name | string | اختياري | 255 حرفًا على الأكثر. | | phone | string | اختياري | 32 حرفًا على الأكثر. ومطلوب في الطلب الحي. | تبحث زيدا عن العميل برقم هاتفه وحده. وتقرأ الرقم المحلي على أنه من بلد المتجر، أو أرسل مفتاح الدولة (+965...). والرقم غير الصالح لا يربط الطلب بعميل، لكن زيدا تحفظ البيع المسجل مع ذلك. كائن الصنف كل سطر في items: | الحقل | النوع | مطلوب | ملاحظات | |---|---|---|---| | name | string | مطلوب | 255 حرفًا على الأكثر. | | quantity | number | مطلوب | أكبر من 0 وأقل من 100,000. وتحفظ زيدا 3 منازل عشرية، فالكيلو والنصف 1.5. ويجب أن يكون عددًا صحيحًا في الطلب الحي. | | unit_price | number | مطلوب | سعر الوحدة الواحدة. انظر «المبالغ». | | external_item_id | string | اختياري | معرف المنتج عندك. 128 حرفًا على الأكثر. | | zyda_item_id | integer | اختياري | معرف نوع المنتج في زيدا، ولا يزيد على 2,147,483,647. ومطلوب في كل سطر من الطلب الحي. | | modifiers | array | اختياري | خيارات السطر، 50 على الأكثر. انظر «كائن الخيار». | كائن الخيار كل عنصر في modifiers: | الحقل | النوع | مطلوب | ملاحظات | |---|---|---|---| | name | string | مطلوب | 255 حرفًا على الأكثر. | | quantity | number | اختياري | إذا تركته أو أرسلته null أو فارغًا، فهو 1. | | unit_price | number | اختياري | إذا تركته أو أرسلته null أو فارغًا، فهو 0. | | external_id | string | اختياري | معرف الخيار عندك. 128 حرفًا على الأكثر. | مصادر الطلبات قيمة channel أحد هذه المفاتيح: website، app، whatsapp، instagram، facebook، tiktok، phone، walk_in، talabat، instashop، deliveroo، keeta، jahez، hungerstation، careem، noon_food، elmenus، breadfast، snoonu، mrsool، the_chefz، rafeeq، other ويفعل المتجر المصادر ويوقفها من الإعداد > النشاط التجاري > مصادر الطلبات. وترفض زيدا الطلب الجديد إذا كان مصدره متوقفًا. أما إعادة إرسال طلب تحفظه زيدا من قبل أو إلغاؤه، فتقبلهما زيدا ولو أوقف المتجر مصدره بعد ذلك. المبالغ كل مبلغ بعملة المتجر، من 0 إلى ما دون 1,000,000,000، وتحفظ زيدا منه 3 منازل عشرية. أرسله رقم JSON أو نصًا من الأرقام. والنص مثل "12.750" يقيك أخطاء التقريب. أرسل الطلب نفسه مرة أخرى يدل channel مع external_order_id على طلب واحد من طلبات المتجر. فإعادة إرساله لا تنشئ طلبًا ثانيًا أبدًا، ولذلك تستطيع أن تعيد الاستدعاء بأمان بعد انتهاء المهلة. وإعادة إرسال البيع المسجل تحدثه (200، "result": "updated"). فتستبدل زيدا الحقول المطلوبة، ويبقى الحقل الاختياري الذي تتركه على قيمته القديمة. وإذا أرسلت items، حلت محل الأسطر كلها. ولتلغي البيع، أرسله مرة أخرى وفيه "status": "canceled". ولا تستطيع أن ترسله مرة أخرى وفيه placed. وإذا وصل استدعاءان للطلب نفسه في وقت واحد، جاء رد أحدهما 409. فأعد إرساله بعد بضع ثوان. الطلبات الحية يصير الطلب الذي فيه "status": "placed" طلبًا حيًا إذا كان المتجر قد فعل إظهار في الطلبات الحالية لمصدره (الإعداد > النشاط التجاري > مصادر الطلبات). فيصل إلى الطلبات الحالية في المتجر كما يصل طلب يدخله أحد الفريق. وفي أي مصدر آخر ترفض زيدا placed برمز 422، فأرسل الطلب حين يكتمل. الطلب الحي المرسل بالواجهة: - لا يرسل إلى العميل أي رسالة؛ - لا يدفع المتجر عنه عمولة طلب لزيدا؛ - لا يكسب به العميل نقاط ولاء ولا استرداد نقود؛ - لا يرسل حدث شراء إلى منصات الإعلانات في المتجر؛ - ومع ذلك يذهب إلى نظام نقاط البيع في المتجر، وينبه الفريق، وتقبله زيدا تلقائيًا إن كان المتجر يقبل الطلبات تلقائيًا. حدود النسخة الأولى. وترفض زيدا كلًا منها برمز 422 ورسالة خاصة به: - delivery_type يجب أن يكون pickup أو أن تتركه، لأن النسخة الأولى لا تأخذ عنوان توصيل. - items مطلوب. - كل سطر يحتاج إلى zyda_item_id، أي معرف نوع المنتج في زيدا. - يجب أن يكون المنتج منشورًا في الفرع وأن يقبل الاستلام. وألا يكون كومبو، وألا يحتاج إلى اختيار خيارات. - quantity في كل سطر عدد صحيح، ولا يزيد الطلب كله على 9,999 وحدة. - customer.phone مطلوب، ويجب أن يكون رقم هاتف صالحًا. - payment_method هو cash أو card_on_delivery أو prepaid. وإن تركته فهو cash. ومعنى prepaid أن المتجر أخذ المال من قبل. ولا تأخذ زيدا أي دفعة. وتسعر قائمة زيدا الطلب، ويحمل الرد total الذي حسبته زيدا. ويرى فريق المتجر modifiers نصًا على السطر. وقد يرفض المتجر الطلب مع ذلك، كأن يكون الفرع مغلقًا أو يكون صنف غير متوفر. فيكون الرد 422، والسبب في errors.order، ورمزه في code. ولا تنشئ زيدا أي طلب. وبعد أن تنشئ زيدا الطلب، ينقله فريق المتجر في زيدا. فتابع حالته بخطافات الويب. ولتلغيه، أرسله مرة أخرى وفيه "status": "canceled" (200، "result": "canceled"؛ ولا ترد زيدا أي مبلغ أبدًا؛ و409 إذا لم يعد المتجر يستطيع إلغاءه). وأي إعادة إرسال أخرى لا تغير شيئًا (200، "result": "unchanged"). الردود كل رد بصيغة JSON. يحمل رد النجاح id في زيدا، وresult، وchannel وexternal_order_id اللذين أرسلتهما، وstatus الطلب في زيدا. وقيمة kind هي imported_order في البيع المسجل وorder في الطلب الحي. وتكون customer_linked بقيمة true إذا وجدت زيدا العميل من رقم هاتفه أو أنشأته. ويحمل الطلب الحي أيضًا order_number وtotal الذي حسبته زيدا. | الرمز | معناه | |---|---| | 201 | الطلب جديد وحفظته زيدا. "result": "created". | | 200 | كان الطلب عند زيدا من قبل. updated: أخذ البيع المسجل القيم الجديدة. unchanged: بقي الطلب الحي المرسل مرة أخرى على حاله. canceled: ألغيت الطلب الحي. | | 400 | المحتوى ليس كائن JSON. | | 401 | المفتاح مفقود أو مجهول أو مبطل. | | 409 | استدعاء آخر يكتب الطلب نفسه الآن، أو لم يعد المتجر يستطيع إلغاء هذا الطلب الحي. | | 413 | المحتوى أكبر من 256 KB. | | 422 | حقل مفقود أو خاطئ، أو رفض المتجر طلبًا حيًا (انظر errors.order). | | 429 | أكثر من 120 استدعاء في الدقيقة لهذا المفتاح. انتظر الثواني المذكورة في Retry-After. | | 503 | لا تستطيع زيدا أخذ الطلب الآن. أرسله مرة أخرى فيما بعد. | في كل رد خطأ رسالة error. وفي رد 422 أيضًا errors، وفيه لكل اسم حقل رسالة أو أكثر. وتسمي زيدا حقول الأسطر بموضعها، مثل items[2].quantity: { "error": "invalid order", "errors": { "placed_at": ["is required"], "items[0].quantity": ["must be greater than 0"] } } أعد إرسال 409 و429 و503 وأخطاء الشبكة بالمحتوى نفسه. ولا تعد إرسال 400 و401 و413 و422 حتى تغير الاستدعاء. مثال: بيع مسجل محتوى الاستدعاء: { "branch_id": 101, "channel": "instashop", "external_order_id": "ERP-100045", "placed_at": "2026-10-14T13:05:00+03:00", "status": "completed", "total": "12.750", "currency": "KWD", "delivery_fee": "0.750", "delivery_type": "delivery", "payment_method": "prepaid", "customer": { "name": "Sample Customer", "phone": "+96550000000" }, "items": [ { "name": "Ribeye steak", "quantity": "1.5", "unit_price": "8.000", "external_item_id": "SKU-RIB", "modifiers": [{ "name": "Sliced thin", "external_id": "MOD-SLICE" }] } ] } الرد 201: { "id": 5012, "result": "created", "kind": "imported_order", "channel": "instashop", "external_order_id": "ERP-100045", "status": "completed", "customer_linked": true } مثال: طلب حي الاستدعاء (فعل المتجر إظهار في الطلبات الحالية للمصدر whatsapp): { "branch_id": 101, "channel": "whatsapp", "external_order_id": "ERP-100046", "placed_at": "2026-10-14T13:20:00+03:00", "status": "placed", "total": "9.500", "currency": "KWD", "delivery_type": "pickup", "payment_method": "cash", "customer": { "name": "Sample Customer", "phone": "+96550000000" }, "items": [ { "name": "Burger patties, 6 pieces", "quantity": 2, "unit_price": "4.750", "zyda_item_id": 123456, "modifiers": [{ "name": "Extra fat" }] } ] } الرد 201: { "id": 880123, "result": "created", "kind": "order", "order_number": "1042", "channel": "whatsapp", "external_order_id": "ERP-100046", "status": "submitted", "customer_linked": true, "total": 9.5 } القواعد والحدود - للمتجر 5 خطافات ويب على الأكثر، و10 مفاتيح API نشطة على الأكثر. - 120 استدعاء في الدقيقة لكل مفتاح. والمحتوى 256 KB على الأكثر. والطلب 200 سطر على الأكثر، والسطر 50 خيارًا على الأكثر. - يحفظ سجل الإرسال 30 يومًا. أسئلة شائعة هل ترسل زيدا إلى العميل رسالة عن طلب أرسلته أنا؟ لا. لا يرسل البيع المسجل ولا الطلب الحي أي شيء إلى العميل. هل يكون الطلب الحي طلب توصيل؟ لا في النسخة الأولى. فالطلب الحي يجب أن يكون pickup. أما طلب التوصيل فأرسله بيعًا مسجلًا حين يكتمل. توقف خطافي. لماذا؟ بعد 50 عملية إرسال فاشلة متتالية، توقف زيدا الخطاف. فأصلح نقطة الاستقبال عندك، ثم شغل إرسال الأحداث مرة أخرى. ويبين سجل الإرسال كل خطأ. مقالات ذات صلة - أعد خطافات الويب ومفاتيح API - اختر مصادر الطلبات التي يسجلها فريقك - أرسل طلباتك إلى جدول بيانات Google