API ریفرنس
ڈیولپرز کے لیے انٹرفیسز: عوامی اینڈ پوائنٹس، چیٹ ویجٹ، لاگ ان اور API کلید کے ساتھ REST-API۔
API ریفرنس Zentor App کے ان انٹرفیسز کو بیان کرتا ہے جن سے آپ اپنی ویب سائٹس اور پروگراموں سے خطاب کر سکتے ہیں: فارمز، پروڈکٹ کنفیگریٹر اور مواد کے لیے عوامی اینڈ پوائنٹس، چیٹ ویجٹ، ڈیمو چیٹ بوٹ اور سنگل سائن آن سمیت لاگ ان۔ ہر اینڈ پوائنٹ صفحہ میتھڈ، پاتھ، توثیق، پیرامیٹرز، درخواست اور جواب کی ایک مثال اور دستاویزی ایرر کوڈز بیان کرتا ہے۔
توثیق: فارمز، پروڈکٹ کنفیگریٹر اور مواد کے اینڈ پوائنٹس بغیر لاگ ان کے قابلِ رسائی ہیں۔ چیٹ ویجٹ کے اینڈ پوائنٹس ہیڈر `X-Widget-Token` میں آپ کے ویجٹ کا ایمبیڈ ٹوکن توقع رکھتے ہیں اور صرف ویجٹ کے لیے منظور شدہ ڈومینز سے کالز قبول کرتے ہیں۔ لاگ ان اینڈ پوائنٹس صارف سیشنز کے لیے ایک ایکسیس ٹوکن (JWT) اور ایک Refresh-Token جاری کرتے ہیں۔
API کلید کے ساتھ API رسائی: اپنے پروگراموں اور سرور-ٹو-سرور کنکشنز کے لیے، `https://zentor-app.de/api/v1` بیس URL پر REST-API دستیاب ہے۔ Zentor درخواست پر آپ کے اکاؤنٹ کے لیے API رسائی فعال کرتا ہے۔ پھر ایڈمنسٹریٹرز ڈیش بورڈ میں "API کلیدیں" کے تحت اپنی کلیدیں بناتے ہیں اور ان کی اجازتیں (Scopes) طے کرتے ہیں - اپائنٹمنٹس اور بکنگز، چیٹ بوٹ، کمیونیکیشن، فائلز، نالج بیس، رپورٹس اور ویب ڈیٹا کے لیے۔ ہر شعبے کے لیے ایک ریڈ اجازت (`<شعبہ>.read`، صرف GET) اور ایک رائٹ اجازت (`<شعبہ>.write`، ریڈ شامل) ہے، مثلاً `appointments.read` یا `knowledge.write`۔ کلید ہیڈر `Authorization: Bearer <API-کلید>` یا متبادل طور پر ہیڈر `X-API-Key` میں بھیجیں۔ `GET /api/v1/me` کے ذریعے آپ چیک کرتے ہیں کہ کلید کس اکاؤنٹ اور کن Scopes سے منسلک ہے۔
مکمل کلید صرف بنانے کے وقت ایک بار دکھائی جاتی ہے۔ اسے محفوظ طریقے سے اور صرف سرور کی طرف رکھیں، کبھی براؤزر کوڈ یا موبائل ایپس میں نہیں۔ کلیدیں ایک میعاد ختم ہونے کی تاریخ حاصل کر سکتی ہیں، گھمائی جا سکتی ہیں اور منسوخ کی جا سکتی ہیں۔ REST-API کے ذریعے صرف وہی فنکشنز قابلِ رسائی ہیں جو آپ کے پیکیج میں شامل ہیں، اور تمام ڈیٹا آپ کے اکاؤنٹ تک محدود رہتا ہے۔ عام خرابیاں: 401 `API_KEY_INVALID`، `API_KEY_EXPIRED` یا `API_KEY_REVOKED` (کلید غائب، غلط، میعاد ختم یا منسوخ ہے)، 403 `API_ACCESS_NOT_ENABLED` (اکاؤنٹ کے لیے API رسائی فعال نہیں)، 403 `API_SCOPE_MISSING` (کلید میں مطلوبہ اجازت نہیں)، 403 `TENANT_NOT_ACTIVE` یا `TENANT_LOCKED` (اکاؤنٹ فعال نہیں یا لاک ہے) اور 404 `API_ENDPOINT_NOT_AVAILABLE` (اینڈ پوائنٹ REST-API کے ذریعے دستیاب نہیں)۔
جوابات اور حدود: تمام اینڈ پوائنٹس JSON کے ساتھ جواب دیتے ہیں۔ کامیاب جواب میں 2xx اسٹیٹس اور `"ok": true` ہوتا ہے؛ ایک ایرر جواب میں مشینی طور پر پڑھنے کے قابل ایرر کوڈ (فیلڈ `error` یا `error.code` میں) اور ایک پیغام شامل ہے۔ فی IP ایڈریس 15 منٹ میں 2,000 درخواستیں ممکن ہیں؛ فارم، تصدیق اور لاگ ان اینڈ پوائنٹس کے لیے سخت تر حدود لاگو ہوتی ہیں، جو متعلقہ صفحے پر بیان کی گئی ہیں۔ تجاوز کی صورت میں، سرور 429 `RATE_LIMIT_EXCEEDED` کے ساتھ جواب دیتا ہے۔ وہ اینڈ پوائنٹس جنہیں غیر idempotent کے طور پر نشان زد کیا گیا ہے، کنکشن منقطع ہونے کے بعد خودکار طور پر دہرائے نہیں جانے چاہئیں، کیونکہ اس سے دوہرے درخواستیں یا پیغامات پیدا ہو سکتے ہیں۔
پاس ورڈز، ٹوکنز، API کلیدیں اور تصدیقی کوڈز صرف ریکویسٹ باڈی یا ہیڈرز میں HTTPS کے ذریعے منتقل کریں - نہ کہ URLs، لاگز یا سپورٹ درخواستوں میں۔