ابنِ تطبيقاً

توسّع التطبيقات حساب المطعم عبر وصول OAuth محدّد النطاق وقابل للإلغاء. يعمل كودك على خوادمك؛ وتحتفظ المنصّة بالسجلّ ودفتر التثبيت وقنوات الفوترة. يأخذك هذا الدليل من الصفر إلى تطبيق مُثبَّت ومُقاس الاستخدام.

1. سجّل تطبيقك

أنشئ تطبيقًا في لوحة تحكم الشركاء: الاسم، والفئة، والنطاقات التي تحتاجها، وعنوان webhook اختياري، ونموذج الفوترة. يؤدّي الإرسال إلى إنشاء عميل OAuth (معرّف العميل + السرّ) ووضع التطبيق قيد المراجعة. بمجرّد موافقة المشرف عليه، يظهر في متجر التطبيقات ويمكن تثبيته.

2. احصل على التثبيت

يثبّت صاحب المطعم تطبيقك من صفحة تفاصيله في متجر التطبيقات، مانحًا النطاقات التي طلبتها. يُنشئ التثبيت AppInstallation و(للتطبيقات المدفوعة) يفرض رسوم الفترة الأولى عبر محفظته.

3. استدعِ واجهة API

بادل رمز OAuth للحساب المُثبِّت، ثم استدعِ واجهة REST به. أبلغ عن الاستخدام، أو استقبل webhooks، أو ضمّن صفحة في لوحة تحكّمهم — مشروح أدناه.

OAuth والرموز

تُصادِق التطبيقات باستخدام OAuth 2.0 (Laravel Passport). تأتي بيانات اعتماد عميلك من لوحة تحكم الشركاء. استخدم تدفّق رمز التفويض القياسي؛ يحمل الرمز الممنوح النطاقات التي وافق عليها المالك عند التثبيت.

# Exchange an authorization code for an access token
curl -X POST https://www.menubarcode.comoauth/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d redirect_uri=YOUR_REDIRECT \
  -d code=AUTH_CODE

# Call the API with the returned bearer token
curl https://www.menubarcode.com/api/v1/restaurants \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

الرموز محدّدة النطاق: الاستدعاء الذي يحتاج orders:read يفشل ما لم يمنحه المالك. اطلب الحدّ الأدنى من المجموعة — يتحقّق المراجعون من ذلك.

رموز الجلسة

للاستدعاءات قصيرة العمر من الخادم إلى المُضمَّن، أنشئ رمز جلسة من تثبيت نشط. تنتهي صلاحية الرموز بعد 60 ثانية.

GET https://www.menubarcode.comapps/{appId}/session-token
# → { "token": "…", "expires_in": 60 }

التطبيقات المضمّنة

إذا أعلن تطبيقك عن embed_url, تستضيفه المنصّة في إطار iframe داخل لوحة تحكم المالك في /apps/{appId}/embed. اقرنه برمز جلسة (أعلاه) لمصادقة الصفحة المضمّنة دون دورة OAuth كاملة.

الـ webhooks

اشترك في الأحداث على webhook_url. تُوضَع التسليمات في طابور، ويُعاد المحاولة بها، وتُوقَّع بمخطّط Standard Webhooks باستخدام سرّ توقيع تطبيقك. يجب أن تكون نقطة نهايتك عنوان HTTPS عامًا (دون مضيفات خاصّة/حلقية/بيانات وصفية) وأن تُعيد 2xx بسرعة.

# A delivery your endpoint receives
POST https://your-app.com/webhooks
webhook-id: msg_...
webhook-timestamp: 1710000000
webhook-signature: v1,BASE64_HMAC
Content-Type: application/json

{ "type": "order.paid", "data": { "order_id": 123, ... } }

تحقّق من التوقيع مقابل سرّك قبل الوثوق بأي حمولة. انظر قائمة الأحداث.

الفوترة بالاستخدام

تقيس التطبيقات المفوترة بالاستخدام الاستهلاك عبر الإبلاغ عن وحدات. يُحتسَب كل تقرير على محفظة المالك بسعرك لكل وحدة. مرّر ref فريدًا لجعل التقرير محايدًا تكراريًا (يُتجاهَل التكرار بنفس المرجع).

curl -X POST https://www.menubarcode.com/api/app/usage \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -d quantity=1 \
  -d ref=unique-key-per-event

تُعيد نقطة النهاية 403 إذا كان الرمز لا ينتمي إلى تطبيق مسجّل أو لم يكن التطبيق مثبّتًا للحساب.

أدلّة إرشادية

اختر نوع الفوترة

• مجاني — دون رسوم عند التثبيت.
• متكرر — سعر ثابت يُحتسَب كل فترة فوترة (افتراضيًا 30 يومًا) من محفظة المالك.
• حسب الاستخدام — سعر لكل وحدة يُفوتَر بحسب إبلاغك عن الاستخدام.

اطلب النطاقات بمسؤولية

اطلب فقط النطاقات التي يستخدمها تطبيقك. تغيير النطاقات على إدراج منشور يعيد التطبيق إلى المراجعة. انظر مرجع النطاقات.

التنظيف عند إلغاء التثبيت

عندما يُلغي المالك التثبيت، تُلغي المنصّة رموز التطبيق وتُطلق app/uninstalled الحدث. أوقف العمل في الخلفية واحذف البيانات المخزّنة لذلك الحساب عند استلامه.

مرجع النطاقات

منعكسة من سجلّ نطاقات OAuth في المنصّة.

أحداث Webhook

الأحداث التي يمكنك الاشتراك فيها اليوم:

متطلّبات الإدراج والمراجعة

قبل أن يوافق المشرف على تطبيقك، يجب أن:

• يطلب فقط النطاقات التي يستخدمها، مع تبرير كلٍّ منها في الوصف.
• يوفّر نقطة نهاية webhook عاملة (HTTPS عامة) إن كان يشترك في الأحداث.
• يعلن تسعيرًا دقيقًا — يُولَّد جدول التسعير في صفحة تفاصيلك منه.
• يتضمّن شعارًا واضحًا ووصفًا وفئة ولقطة شاشة واحدة على الأقل.
• يتعامل مع إلغاء التثبيت بنظافة (إلغاء الوصول، إيقاف الفوترة، حذف بيانات الحساب).

تعديلات البيانات الوصفية (الشعار، الوصف، لقطات الشاشة، الروابط) تُنشر فورًا؛ أمّا تغييرات السعر أو النطاق فتعيد إدراج المراجعة في الطابور.