REST API

ہر imatic پروڈکٹ ایک ورژن شدہ REST API کے ساتھ آتا ہے تاکہ آپ اسے اپنے کوڈ سے خودکار بنا سکیں۔ اس صفحے کے اصول — آپ کیسے تصدیق کرتے ہیں، API کیز کیسے کام کرتی ہیں، ویب ہکس کیسے دستخط ہوتے ہیں، اور صفحہ بندی، شرح کی حدود، اور خرابیاں کیسے برتاؤ کرتی ہیں — مصنوعات میں ایک جیسے ہیں۔ جو مختلف ہوتا ہے وہ ہر پروڈکٹ کے ظاہر کردہ وسائل ہیں، جو اس کے ڈویلپر صفحے پر دستاویز کیے گئے ہیں۔

مثالیں وضاحتی ہیں

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

تصدیق

imatic دو مختلف کالرز کے لیے دو قسم کے کریڈینشلز استعمال کرتا ہے:

JWT (سیشن ٹوکن) — وہ جو ویب ایپ ای میل اور پاس ورڈ سے سائن ان کرنے کے بعد استعمال کرتی ہے۔ یہ براؤزر میں آپ کی نمائندگی کرتا ہے اور قلیل المدت ہوتا ہے۔ آپ اسے براہ راست منظم نہیں کرتے؛ ایپ کرتی ہے۔
اسکوپ شدہ API key — وہ جو آپ کا کوڈ v1 REST API کو کال کرنے کے لیے استعمال کرتا ہے۔ آپ اسے خود بناتے ہیں، یہ واضح اسکوپس رکھتی ہے، اور یہ کسی براؤزر سیشن کے ساتھ ختم نہیں ہوتی۔

سرور تا سرور کالز کے لیے، ہمیشہ ایک API کلید استعمال کریں — کبھی اپنا پاس ورڈ یا کاپی کیا ہوا سیشن ٹوکن نہیں۔

ایک API کلید بھیجنا

کلید کو Authorization ہیڈر میں Bearer ٹوکن کے طور پر پاس کریں:

curl https://<product-host>/v1/event-types \
  -H "Authorization: Bearer cal_abc123.s3cr3t_keymaterial" \
  -H "Content-Type: application/json"

API کیز کیسے کام کرتی ہیں

آپ ہر پروڈکٹ کے ڈویلپر علاقے میں API کیز بناتے اور منظم کرتے ہیں — مثال کے طور پر Calendar کا Developers → API keys اور Survey کا Developers → API keys۔ ایک کلید کی تین خصوصیات سمجھنے کے قابل ہیں:

prefix.secret فارمیٹ — ایک کلید کا ایک عوامی prefix اور ایک خفیہ حصہ ہوتا ہے، جو ایک ڈاٹ سے جڑے ہوتے ہیں (مثال کے طور پر cal_abc123.s3cr3t_keymaterial — Calendar کیز ایک مختصر cal_ prefix استعمال کرتی ہیں)۔ prefix imatic کو فہرستوں اور لاگز میں کلید کی شناخت کرنے دیتا ہے؛ راز وہ ہے جو ثابت کرتا ہے کہ یہ آپ کی ہے۔
ایک بار دکھایا جاتا ہے — مکمل کلید کی قدر صرف اسی لمحے دکھائی جاتی ہے جب آپ اسے بناتے ہیں۔ اس کے بعد، صرف prefix نظر آتا ہے۔
اسکوپس — ہر کلید ان اقدامات تک محدود ہوتی ہے جو آپ اسے دیتے ہیں۔ Calendar کے اسکوپس slots:read، bookings:read، bookings:write، اور mcp ہیں (mcp اسکوپ وہ ہے جو کسی AI ایجنٹ کی کلید کو درکار ہوتا ہے — دیکھیں AI ایجنٹس کے لیے MCP)۔ ایسی درخواست جو کسی کلید کے اسکوپ سے تجاوز کرتی ہے، مسترد کر دی جاتی ہے۔

API کیز کو پاس ورڈز کی طرح سمجھیں

ایک کلید کا راز صرف ایک بار، تخلیق کے وقت، دکھایا جاتا ہے۔ اسے اسی وقت کاپی کریں اور کسی سیکریٹ مینیجر یا ماحولیاتی متغیر میں محفوظ کریں — کبھی سورس کنٹرول، اسکرین شاٹ، یا کسی مشترکہ دستاویز میں نہیں۔ اگر کوئی کلید بے نقاب ہو جائے، تو اسے ڈویلپر علاقے میں منسوخ کریں اور ایک متبادل بنائیں۔ منسوخی فوراً نافذ ہو جاتی ہے۔

ویب ہکس

تبدیلیوں کے لیے پول کرنے کے بجائے، ایک ویب ہک URL رجسٹر کریں اور imatic کسی واقعے کے ہونے پر اس پر ایک ایونٹ POST کرے گا — مثال کے طور پر Calendar میں کوئی بکنگ بنتی ہے یا Survey میں کوئی جواب جمع کرایا جاتا ہے۔ آپ ہر پروڈکٹ کے Developers → Webhooks علاقے میں ویب ہک اینڈ پوائنٹس منظم کرتے ہیں، جہاں آپ ایک ٹیسٹ ترسیل بھی بھیج سکتے ہیں۔

ایک ترسیل تقریباً ایسی نظر آتی ہے:

POST /your/webhook/endpoint HTTP/1.1
Content-Type: application/json
X-Imatic-Signature: t=1718900000,v1=9f86d081884c7d659a2feaa0c55ad015...

{
  "event": "booking.created",
  "data": { "...": "event-specific payload" }
}

دستخط کی تصدیق

ہر ترسیل آپ کے اینڈ پوائنٹ کے دستخطی راز کا استعمال کرتے ہوئے HMAC-SHA256 سے دستخط شدہ ہوتی ہے، ایک Stripe طرز کے X-Imatic-Signature ہیڈر میں۔ ہیڈر دو فیلڈز رکھتا ہے: t، بھیجنے کے وقت کے unix-epoch سیکنڈ، اور v1، سٹرنگ ${t}.${body} کا hex HMAC (ٹائم اسٹیمپ، ایک لفظی ڈاٹ، پھر بالکل خام درخواست باڈی)۔ تصدیق کے لیے، ہیڈر کو تقسیم کریں، اپنے دستخطی راز کے ساتھ t + "." + rawBody پر v1 دوبارہ شمار کریں، اور مستقل وقت میں موازنہ کریں۔ اگر وہ میل نہ کھائیں تو مسترد کریں — اور اختیاری طور پر جب t چند منٹ سے پرانا ہو تو مسترد کریں تاکہ ری پلے سے بچاؤ ہو۔

import crypto from "node:crypto";

function isValid(rawBody, signatureHeader, signingSecret) {
  // Header shape: "t=<epoch-seconds>,v1=<hex hmac>"
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((kv) => kv.split("=")),
  );
  const { t, v1 } = parts;
  if (!t || !v1) return false;

  // Sign the timestamped body: `${t}.${rawBody}` — NOT the raw body alone.
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  // Constant-time comparison to avoid timing attacks.
  const a = Buffer.from(v1);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

ہر پروڈکٹ کے لیے درست اسکیم

اوپر دی گئی t=…,v1=… اسکیم Calendar کی ہے۔ کوئی تصدیق کنندہ شپ کرنے سے پہلے ہر پروڈکٹ کے ڈویلپر صفحے پر ہیڈر کا نام، فیلڈز، اور دستخط شدہ سٹرنگ کی تصدیق کریں۔

تیزی سے جواب دیں، بعد میں عمل کریں

وصولی تسلیم کرنے کے لیے جلدی ایک 2xx واپس کریں، پھر کوئی بھی سست کام غیر متزامن طور پر کریں۔ اگر آپ کا اینڈ پوائنٹ سست ہو یا خرابی دے، تو ترسیلیں دوبارہ کوشش کی جا سکتی ہیں۔

صفحہ بندی

فہرست اینڈ پوائنٹس نتائج کو صفحات میں واپس کرتے ہیں تاکہ ایک واحد کال کو کبھی ہر چیز لوڈ نہ کرنی پڑے۔ درخواست پر صفحہ بندی کے پیرامیٹرز پاس کریں اور اگلا صفحہ حاصل کرنے کے لیے جواب پر صفحہ بندی کا میٹا ڈیٹا پڑھیں۔

curl "https://<product-host>/v1/bookings?limit=25" \
  -H "Authorization: Bearer cal_abc123.s3cr3t_keymaterial"

{
  "success": true,
  "data": [ { "...": "one item per result" } ],
  "pagination": { "page": 1, "limit": 20, "total": 0, "pages": 0 }
}

اگلے صفحے کی درخواست کرتے رہیں جب تک مزید نتائج نہ ہوں۔

شرح کی حد بندی

API کیز پر شرح کی حد لگائی جاتی ہے تاکہ پلیٹ فارم منصفانہ اور مستحکم رہے۔ اگر آپ حد سے تجاوز کریں، تو API HTTP 429 Too Many Requests کے ساتھ جواب دیتا ہے۔ اینڈ پوائنٹ کو بار بار مارنے کے بجائے پیچھے ہٹیں اور دوبارہ کوشش کریں — ترجیحاً ایکسپوننشل بیک آف اور jitter کے ساتھ۔

{
  "success": false,
  "error": "rate_limited",
  "message": "Too many requests. Please retry after a short delay."
}

خرابی کا انتظام

خرابیاں معیاری HTTP اسٹیٹس کوڈز کے ساتھ ایک JSON باڈی استعمال کرتی ہیں جو بیان کرتی ہے کہ کیا غلط ہوا۔ وہ کوڈز جو آپ اکثر دیکھیں گے:

400 — درخواست خراب تھی یا توثیق میں ناکام رہی۔
401 — API کلید غائب یا غلط۔
403 — کلید درست ہے لیکن اس اقدام کے لیے اسکوپ (یا org رسائی) نہیں رکھتی۔
404 — وسیلہ موجود نہیں یا اس کلید کو نظر نہیں آتا۔
409 — ایک تنازع، جیسے ایسا سلاٹ بک کرنے کی کوشش جو ابھی لیا گیا تھا۔
429 — شرح محدود؛ پیچھے ہٹیں اور دوبارہ کوشش کریں۔
5xx — سرور سائیڈ خرابی؛ عارضی ناکامیوں کو دوبارہ کوشش کریں۔

ایک عام خرابی کا لفافہ:

{
  "success": false,
  "error": "validation_failed",
  "message": "A human-readable explanation of the problem."
}

پروڈکٹ کے لحاظ سے وسائل

اوپر دیے گئے اصول مشترکہ ہیں، لیکن ہر پروڈکٹ اپنے اینڈ پوائنٹس ظاہر کرتا ہے۔ درست وسائل، پیرامیٹرز، اور فیلڈ ناموں کے لیے پروڈکٹ کے ڈویلپر صفحے سے شروع کریں:

Calendar — ایونٹ ٹائپس، دستیابی slots، بکنگز (بنائیں، دوبارہ شیڈول کریں، منسوخ کریں)، کیلنڈرز، ویب ہکس، API کیز، اور ایونٹ لنکس۔ ویب ہک ایونٹس booking.created، booking.cancelled، booking.rescheduled، اور booking.no_show ہیں۔ دیکھیں ڈویلپرز کے لیے Calendar۔
Survey — فارمز، جوابات، جوابات کی مجموعہ بندی، AI فارم جنریشن، اور ویب ہکس (form.published، response.submitted)۔ دیکھیں ڈویلپرز کے لیے Survey۔
Voice Portal — ایجنٹس، مہمات، اور رابطے، نیز ٹولز اور MCP سرور رجسٹریشن۔ دیکھیں ایجنٹس کے لیے ٹولز اور MCP۔

تصدیق​

ایک API کلید بھیجنا​

API کیز کیسے کام کرتی ہیں​

ویب ہکس​

دستخط کی تصدیق​

صفحہ بندی​

شرح کی حد بندی​

خرابی کا انتظام​

پروڈکٹ کے لحاظ سے وسائل​

متعلقہ​