ایک ایپ بنائیں

ایپس ایک ریستوران کے اکاؤنٹ کو محدود دائرہ کار، قابلِ منسوخی OAuth رسائی کے ذریعے وسعت دیتی ہیں۔ آپ کا کوڈ آپ کے سرورز پر چلتا ہے؛ پلیٹ فارم رجسٹری، انسٹال لیجر، اور بلنگ ریلز رکھتا ہے۔ یہ گائیڈ آپ کو صفر سے ایک انسٹال شدہ، میٹرڈ ایپ تک لے جاتی ہے۔

1۔ اپنی ایپ رجسٹر کریں

اس میں ایک ایپ بنائیں پارٹنر ڈیش بورڈ: نام، زمرہ، جو دائرہ کار آپ کو چاہیے، ایک اختیاری webhook URL، اور آپ کا بلنگ ماڈل۔ جمع کرانے سے ایک OAuth کلائنٹ بنتا ہے (client id + secret) اور ایپ کو جائزے میں ڈال دیتا ہے۔ ایک بار جب ایڈمن اسے منظور کر لے، یہ App Store میں ظاہر ہوتی ہے اور انسٹال کی جا سکتی ہے۔

2۔ انسٹال ہو جائیں

ایک ریستوران مالک آپ کی ایپ کو اس کے App Store تفصیلی صفحے سے انسٹال کرتا ہے، آپ کے طلب کردہ دائرہ کار دیتے ہوئے۔ انسٹالیشن بناتی ہے ایک AppInstallation اور (ادا شدہ ایپس کے لیے) ان کے والٹ کے ذریعے پہلی مدت وصول کرتی ہے۔

3۔ API کال کریں

انسٹال کرنے والے اکاؤنٹ کے لیے ایک OAuth ٹوکن تبادلہ کریں، پھر کال کریں REST API اس کے ساتھ۔ استعمال رپورٹ کریں، webhooks وصول کریں، یا ان کے ڈیش بورڈ میں ایک صفحہ ایمبیڈ کریں — نیچے احاطہ کیا گیا۔

OAuth اور ٹوکنز

ایپس OAuth 2.0 (Laravel Passport) سے توثیق کرتی ہیں۔ آپ کی کلائنٹ اسناد پارٹنر ڈیش بورڈ سے آتی ہیں۔ معیاری authorization-code flow استعمال کریں؛ دیا گیا ٹوکن وہ دائرہ کار رکھتا ہے جو مالک نے انسٹال پر منظور کیے۔

# 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 راؤنڈ ٹرپ کے بغیر ایمبیڈڈ صفحے کی توثیق کے لیے اسے ایک سیشن ٹوکن (اوپر) کے ساتھ جوڑیں۔

ویب ہکس

اپنی ایپ کے پر ایونٹس کو سبسکرائب کریں webhook_url. ڈیلیوریز قطار بند، دوبارہ کوشش شدہ، اور اس کے ساتھ دستخط شدہ ہوتی ہیں Standard Webhooks اسکیم آپ کی ایپ کے signing secret کا استعمال کرتے ہوئے۔ آپ کا اینڈ پوائنٹ عوامی HTTPS URL ہونا ضروری ہے (کوئی private/loopback/metadata میزبان نہیں) اور واپس کرے 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, ... } }

کسی payload پر بھروسہ کرنے سے پہلے اپنے secret کے خلاف دستخط کی تصدیق کریں۔ دیکھیں ایونٹ فہرست.

استعمال بلنگ

استعمال بل شدہ ایپس یونٹس رپورٹ کر کے کھپت ماپتی ہیں۔ ہر رپورٹ آپ کی فی یونٹ قیمت پر مالک کے والٹ سے وصول کی جاتی ہے۔ ایک منفرد پاس کریں ref کسی رپورٹ کو idempotent بنانے کے لیے (اسی 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 scope رجسٹری سے منعکس۔

Webhook ایونٹس

آج آپ جن ایونٹس کو سبسکرائب کر سکتے ہیں:

لسٹنگ اور جائزے کے تقاضے

اس سے پہلے کہ ایڈمن آپ کی ایپ کو منظور کرے، اسے ضرور:

• صرف وہ دائرہ کار طلب کرے جو یہ استعمال کرتی ہے، ہر ایک کا تفصیل میں جواز پیش کرے۔
• ایک کام کرنے والا webhook اینڈ پوائنٹ فراہم کرے (عوامی HTTPS) اگر یہ ایونٹس سبسکرائب کرتی ہے۔
• درست قیمت کا اعلان کرے — آپ کے تفصیلی صفحے پر قیمت ٹیبل اسی سے تیار ہوتی ہے۔
• ایک واضح ٹیگ لائن، تفصیل، زمرہ، اور کم از کم ایک اسکرین شاٹ شامل کرے۔
• ان انسٹال کو صاف طور پر سنبھالے (رسائی منسوخ کرے، بلنگ روکے، اکاؤنٹ ڈیٹا حذف کرے)۔

میٹا ڈیٹا ترامیم (ٹیگ لائن، تفصیل، اسکرین شاٹس، لنکس) فوری طور پر لائیو ہو جاتی ہیں؛ قیمت یا دائرہ کار کی تبدیلیاں جائزے کو دوبارہ قطار میں لگا دیتی ہیں۔