وصّل بيانات المنيو بتاعتك بأي نظام تاني: الـ API العام

طلب الزبون بيوصل الواتساب بتاعك ولوحة الطلبات. ده كويس لفريق المطعم. لكن مش كافي للوكالة اللي بتدير الحساب لعميل، ولا لمقدم نظام كاشير عايز يربط menu-MENA بنظامه من غير ما يطلب من الموظفين يكتبوا أي حاجة تاني بإيدهم. علشان كده menu-MENA فيها API صغير: أربع نقاط وصول كلها GET، مفتاح واحد، وJSON عادي.

فين تلاقي المفتاح

روح لـ Admin → API access. الصفحة دي للمالك بس: أي مدير يفتحها بيترجع على طول للوحة الرئيسية، ومش هيشوف مفتاح خالص. دوس على Generate API key وهياخد مفتاح يبدأ بـ mcx_live_، ظاهر في حقل للقراءة بس مع أيقونة نسخ جنبه. تحته فيه مثال curl جاهز بمفتاحك الحقيقي داخل فيه على طول، تقدر تلزقه في الـ terminal وتاخد رد حقيقي من أول مرة، من غير ما تخمّن شكل الـ header.

لو محتاج توقف تكامل قديم، دوس إعادة الإنشاء. المفتاح القديم بيبقى غير صالح في نفس اللحظة، وده لازم تفتكره قبل ما تغيّر المفتاح في نظام شغال فعلاً: حدّث التكامل الأول، وبعدين اعمل إعادة الإنشاء، مش العكس.

أربع نقاط وصول، كلها قراءة

• GET /api/public/v1/me بترجع رقم حسابك، الـ slug، الاسم، والباقة. دي نقطة اختبار الاتصال، اللي أي خطوة "test trigger" في Zapier أو أي فحص صحة للنظام هيبدأ بيها.
• GET /api/public/v1/menu بترجع نفس الأقسام والأصناف اللي بتظهر في صفحة المنيو العامة، بنفس الهيكل اللي لوحة التحكم بتعدّل فيه.
• GET /api/public/v1/orders?since=<ms>&limit=<n> بترجع سجلات الطلبات.
• GET /api/public/v1/reservations?since=<ms>&limit=<n> بترجع سجلات الحجوزات، بنفس شكل الباراميترات.

كل رد بييجي داخل { "data": ... }. مفيش حاجة تكتبها، بس تقراها: ولا نقطة من الأربعة بتقبل POST أو PUT أو DELETE. لو التكامل بتاعك محتاج يعدّل صنف منيو أو ينشئ طلب من برّه لوحة التحكم، النسخة دي مش بتعمل كده.

تقرا الطلبات من غير ما تفوّت حاجة

/orders و/reservations مبنيين كمصدر سحب دوري، نفس اللي Zapier بيسميه Polling Trigger: إنت اللي بتسأل كل فترة، لأن مفيش webhook لسه. لو ناديت من غير since، هتاخد آخر عدد من السجلات على حسب الـ limit (25 افتراضياً، أقصى حد 100)، الأحدث الأول، كعينة مما هو موجود. لو ناديت وحددت since بآخر createdAt شفته، هتاخد كل حاجة بعده، بس المرة دي الأقدم الأول، عشان تتقدم خطوة خطوة من غير ما تسيب فجوة.

قلب الترتيب في المرة التانية مش صدفة. لو جبت الأحدث الأول وقطعت عند الـ limit، أي دفعة طلبات كبيرة بين نداءين، وقت الزحمة مثلاً، ممكن تدفع سجلات أقدم لسه ما شفتهاش برّه الصفحة وبرّه الرد خالص. الترتيب التصاعدي مع فلتر > على createdAt معناه مفيش حاجة بتضيع بين النداءات، أقصى حاجة بتتأخر لنداء زيادة.

سجل الطلب بيحمل status وchannel وlines (الصنف والكمية والسعر) وmeta (تناول في المطعم أو تيك أواي، ورقم الترابيزة)، وtotalPrice وtotalQty وcurrency. بيحمل كمان taxAmount وdiscountAmount وcouponCode، كل واحد فيهم ممكن يكون فاضي. الحقول التلاتة دي موجودة عشان تقدر تراجع الإجمالي مقابل الأصناف بنفسك: طلب فيه كوبون، مجموع أصنافه بيبقى أعلى من totalPrice، وحساب فيه ضريبة مضافة، جزء الضريبة مش ظاهر في أي مكان تاني في الرد. قيمة status بتطابق اللي فريقك شايفه على لوحة الطلبات بالظبط، حتى الطلب اللي اتسجل قبل ما اللوحة دي تتعمل، بيظهر كـ new، مش تحت اسم قديم داخلي كان لازم تعامله كحالة خاصة.

حدود الطلبات والأخطاء

ستين طلب في الدقيقة لكل مفتاح API. تعدّى الرقم ده وهتاخد 429. فيه حد تاني تحته، مربوط بعنوان الـ IP مش بالمفتاح، بيوقف أي سيل من Bearer tokens غلط قبل ما توصل لقاعدة البيانات خالص، فتكامل معطوب بيحاول بمفتاح غلط في حلقة مش هيستهلك عدد قراءاتك. مفتاح ناقص أو غلط بيرجع 401 بشكل { "error": { "message": "..." } }، بنفس الشكل ده كل مرة.

اللي لسه مش موجود

مفيش كتابة. مفيش webhook، سحب دوري بس. ومفيش تطبيق Zapier جاهز: الـ API اللي فوق ده جاهز هندسياً بالكامل، وبالظبط الشكل اللي أي trigger زي "New Order" أو "New Reservation" في Zapier هيتبني عليه، لكن نشر تطبيق فعلي في دليل Zapier خطوة لسه محدش عملها. لو بتربط تكامل النهارده، إنت بتنادي الـ API على طول.

مين فعلاً محتاج الحاجة دي

أغلب أصحاب المطاعم عمرهم ما هيفتحوا الصفحة دي. هي للوكالة اللي بتدير كذا حساب وعايزة عدد الطلبات يظهر على لوحة تحكم للعميل من غير ما تدخل كل لوحة تحكم لوحدها، أو لمقدم نظام الكاشير اللي يفضّل ينادي /orders كل ثلاثين ثانية عن ما يطلب من موظفي العميل يدخلوا نفس البيانات يدوياً تاني. صلاحيات المالك والمدير اللي بتتحكم في لوحة التحكم، بتتحكم في الصفحة دي كمان: لو إنت مدير وبتبني التكامل بنفسك، لازم برضه المالك يديك المفتاح، لأن مفيش طريق للمديرين يوصلوا بيه للمفتاح لوحدهم.