کیلنڈر API اور MCP
imatic Calendar میں آپ جو کچھ بھی کرتے ہیں، اسے خودکار بنا سکتے ہیں۔ سلاٹس کے بارے میں پوچھنے اور بکنگز بنانے کے لیے REST API استعمال کریں، حقیقی وقت میں ایونٹس پر ردعمل دینے کے لیے ویب ہکس، اور کسی AI ایجنٹ کو آپ کی طرف سے بکنگ کرنے دینے کے لیے MCP سرور۔ یہ صفحہ ان ڈویلپرز کے لیے ہے جو imatic Calendar کو اپنی ایپس اور ٹولز میں جوڑ رہے ہیں۔
آپ اپنے ڈیش بورڈ میں Developers کے تحت کریڈینشلز کا انتظام کرتے ہیں۔
API keys اور Webhooks کے صفحات ایک اکاؤنٹ ایڈمن (org admin یا super admin) کے زیر انتظام ہوتے ہیں۔ اگر آپ کو وہ اپنے ڈیش بورڈ میں نظر نہیں آتے، تو اپنے اکاؤنٹ پر کسی ایڈمن سے کہیں کہ آپ کے لیے کوئی کلید جاری کرے یا ویب ہک سیٹ اپ کرے۔
تصدیق اور API کیز
API کو کالز ایک API key کے ساتھ تصدیق کی جاتی ہیں جو بطور bearer token بھیجی جاتی ہے:
Authorization: Bearer <your_api_key>
Developers → API keys کے تحت کیز کا انتظام کریں، جہاں آپ یہ کر سکتے ہیں:
- ایک کلید بنائیں — جب راز دکھایا جائے تو اسے کاپی کریں؛ یہ دوبارہ نہیں دکھایا جاتا۔
- اپنی کیز کی فہرست بنائیں اور دیکھیں کہ ہر ایک کس لیے ہے۔
- اگر کوئی کلید لیک ہو جائے یا اب اس کی ضرورت نہ ہو تو اسے فوراً منسوخ کریں۔
- اسکوپس تفویض کریں — ہر کلید صرف وہی اجازتیں رکھتی ہے جو آپ دیتے ہیں، اس لیے ایک صرف پڑھنے والی کلید بکنگز کی فہرست بنا سکتی ہے لیکن کبھی انہیں بنا یا منسوخ نہیں کر سکتی۔
دستیاب اسکوپس یہ ہیں:
| اسکوپ | کیا دیتا ہے |
|---|---|
slots:read | کسی ایونٹ ٹائپ کے لیے دستیاب وقت کے سلاٹ پڑھیں |
bookings:read | بکنگز کی فہرست بنائیں اور پڑھیں |
bookings:write | بکنگز بنائیں، منسوخ کریں، اور دوبارہ شیڈول کریں |
mcp | MCP سرور استعمال کریں (ایک چھتری جو slots:read، bookings:read، اور bookings:write کو بھی شامل کرتی ہے) |
ایک کلید اپنے اسکوپس کے اندر آپ کے اکاؤنٹ تک رسائی دیتی ہے۔ اسے کسی سیکریٹ مینیجر یا ماحولیاتی متغیر میں محفوظ کریں، کبھی کلائنٹ سائیڈ کوڈ یا عوامی ریپو میں نہیں۔ اگر یہ بے نقاب ہو جائے تو فوراً منسوخ اور تبدیل کریں۔
REST API v1
REST API کو /v1 بیس پاتھ کے تحت پیش کیا جاتا ہے اور یہ JSON واپس کرتا ہے۔ دستیاب وسائل یہ ہیں:
- Event types — اپنی ایونٹ ٹائپس کی فہرست بنائیں اور پڑھیں، نیز کسی ایونٹ ٹائپ کی نقل بنائیں (
POST /v1/event-types/:code/duplicate)۔ (بنانا/ترمیم/حذف کرنا ڈیش بورڈ میں کیا جاتا ہے۔) - Slots — کسی ایونٹ ٹائپ کے لیے دستیاب وقت کے سلاٹس کے بارے میں پوچھیں (وہی دستیاب اوقات جو آپ کے بکنگ صفحے پر دکھائے جاتے ہیں، تمام بفرز، نوٹس اور حدود لاگو کے ساتھ)۔
- Bookings — مکمل CRUD کے ساتھ reschedule: ایک بکنگ بنائیں، بکنگز کی فہرست بنائیں اور پڑھیں، منسوخ کریں، اور کسی کو نئے وقت پر منتقل کریں۔
GET /v1/bookings/statsمجموعی بکنگ کی تعداد واپس کرتا ہے۔ - Event links — کسی ایونٹ ٹائپ سے بندھے ہوئے واحد استعمال والے بکنگ لنکس بنائیں، فہرست بنائیں، اور منسوخ کریں (
POST/GET /v1/event-types/:code/links،DELETE /v1/event-links/:linkCode)۔ - Webhooks — اپنی ویب ہک سبسکرپشنز کو پروگرامی طور پر منظم کریں۔
- Users / me —
GET /v1/users/meAPI کلید کی شناخت واپس کرتا ہے (تصدیق شدہ اکاؤنٹ اور org)۔ - Calendars — اپنے منسلک کیلنڈرز کے ساتھ کام کریں (دیکھیں انٹیگریشنز)۔
ایک عام خودکار عمل: کسی ایونٹ ٹائپ کے لیے slots کے بارے میں پوچھیں، پھر اس سلاٹ کے لیے ایک booking بنائیں جو آپ کے صارف نے چنا — وہی اٹامک، دوہری بکنگ نہ ہونے کی ضمانت جو بکنگ صفحہ استعمال کرتا ہے، API پر بھی لاگو ہوتی ہے۔
ویب ہکس
ویب ہکس ایونٹس کو آپ کے سرور پر اسی لمحے بھیج دیتے ہیں جب وہ پیش آتے ہیں، تاکہ آپ کو پول نہ کرنا پڑے۔ انہیں Developers → Webhooks کے تحت منظم کریں۔
- بکنگ ایونٹس وصول کرنے کے لیے کسی URL کو سبسکرائب کریں۔ ایونٹس بالکل یہ ہیں:
booking.created،booking.cancelled،booking.rescheduled، اورbooking.no_show۔ - ہر ترسیل HMAC کے ساتھ دستخط شدہ ہوتی ہے — پے لوڈ پر اعتماد کرنے سے پہلے دستخط ہیڈر کو اپنے ویب ہک کے راز کے خلاف تصدیق کریں تاکہ یقین ہو کہ درخواست حقیقتاً imatic Calendar سے آئی ہے۔
- جب آپ بنا رہے ہوں تو اپنے اینڈ پوائنٹ پر ایک نمونہ ایونٹ بھیجنے کے لیے بلٹ ان Test ایکشن استعمال کریں، تاکہ آپ لائیو ہونے سے پہلے اپنے ہینڈلر کے کام کرنے کی تصدیق کر سکیں۔
دستخط X-Imatic-Signature ہیڈر میں، Stripe طرز کے فارمیٹ میں سفر کرتا ہے:
X-Imatic-Signature: t=<unix-epoch-seconds>,v1=<hmac-sha256>
تصدیق کرنے کے لیے: t اور خام درخواست باڈی لیں، HMAC-SHA256(secret, "<t>.<body>") کا حساب لگائیں (ٹائم اسٹیمپ اور باڈی ایک لفظی ڈاٹ سے جڑے ہوئے)، اسے hex میں انکوڈ کریں، اور اس کا v1 سے موازنہ کریں۔ اگر وہ میل نہ کھائیں تو درخواست مسترد کریں۔
کسی بھی ویب ہک کو مسترد کریں جس کا HMAC دستخط میل نہیں کھاتا۔ یہی ایک قابل اعتماد خودکار عمل اور ایک کھلے دروازے کے درمیان فرق ہے۔
MCP سرور
imatic Calendar ایک Model Context Protocol (MCP) سرور کے ساتھ آتا ہے، تاکہ AI ایجنٹس اور اسسٹنٹس اچھی طرح متعین ٹولز کے ذریعے آپ کی دستیابی پڑھ سکیں اور بکنگز کا انتظام کر سکیں — REST API جیسی ہی API کلید کی تصدیق اور اسکوپس استعمال کرتے ہوئے۔
سرور سات ٹولز ظاہر کرتا ہے:
| ٹول | یہ کیا کرتا ہے |
|---|---|
list_event_types | آپ کی قابل بکنگ ایونٹ ٹائپس کی فہرست بنائیں |
list_slots | کسی ایونٹ ٹائپ کے لیے کھلے سلاٹس حاصل کریں |
create_booking | ایک سلاٹ بک کریں |
cancel_booking | ایک بکنگ منسوخ کریں |
reschedule_booking | ایک بکنگ کو نئے وقت پر منتقل کریں |
list_bookings | موجودہ بکنگز کی فہرست بنائیں |
get_booking | اس کے کوڈ کے ذریعے ایک واحد بکنگ پڑھیں |
اپنے MCP کے قابل کلائنٹ کو سرور کی طرف اشارہ کریں، کسی API کلید سے تصدیق کریں، اور آپ کا ایجنٹ "پریا جمعرات کو کب فارغ ہے؟" کا جواب دے سکتا ہے اور سلاٹ بک کر سکتا ہے — یہ سب اس کلید کو آپ کے دیے گئے اسکوپس کے اندر۔
اکاؤنٹ کا اپنا پروفائل REST کے ذریعے GET /v1/users/me سے پڑھا جاتا ہے، نہ کہ کسی MCP ٹول کے ذریعے۔
کسی AI ایجنٹ کو صرف اتنے ٹولز والی کلید دیں جتنے اسے درکار ہوں۔ اگر اسے صرف دستیابی پڑھنی ہے، تو اسے منسوخ یا دوبارہ شیڈول کرنے کی اجازتیں نہ دیں۔
اگلے اقدامات
- انٹیگریشنز — دو طرفہ ہم آہنگی کے لیے Google اور Outlook جوڑیں۔
- ایونٹ ٹائپس — وہ وسیلہ جس کے گرد آپ کی زیادہ تر API کالز گھومتی ہیں۔
- آپ کا عوامی بکنگ صفحہ — وہ بغیر کوڈ والا راستہ جس کی آپ کی خودکار کارروائیاں نقل کرتی ہیں۔