إنتقل إلى المحتوى الرئيسي

REST API

يأتي كل منتج من imatic مزوّدًا بـ REST API مُصدَّرة الإصدار حتى تتمكن من أتمتته من كودك الخاص. الاصطلاحات في هذه الصفحة — كيف تصادق، وكيف تعمل مفاتيح API، وكيف تُوقَّع خطافات الويب، وكيف يتصرف ترقيم الصفحات وحدود المعدل والأخطاء — هي نفسها عبر المنتجات. ما يختلف هو الموارد التي يكشفها كل منتج، والموثّقة على صفحة المطوّرين الخاصة به.

الأمثلة توضيحية

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

المصادقة​

تستخدم imatic نوعين من بيانات الاعتماد، لمستدعيين مختلفين:

  • JWT (رمز الجلسة) — ما يستخدمه تطبيق الويب بعد تسجيل الدخول بالبريد الإلكتروني وكلمة المرور. يمثّل أنت في المتصفح وهو قصير العمر. لا تديره مباشرة؛ يفعل ذلك التطبيق.
  • مفتاح API ذو النطاقات — ما يستخدمه كودك لاستدعاء REST API الخاصة بـ v1. تنشئه بنفسك، ويحمل نطاقات صريحة، ولا تنتهي صلاحيته مع جلسة المتصفح.

للاستدعاءات من خادم إلى خادم، استخدم دائمًا مفتاح API — لا كلمة مرورك أبدًا ولا رمز جلسة منسوخًا.

إرسال مفتاح API​

مرّر المفتاح كرمز حامل في الترويسة Authorization:

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

كيف تعمل مفاتيح API​

تنشئ مفاتيح API وتديرها في منطقة المطوّرين لكل منتج — على سبيل المثال للمطوّرين ← مفاتيح API في Calendar وللمطوّرين ← مفاتيح API في Survey. للمفتاح ثلاث خصائص جديرة بالفهم:

  • تنسيق prefix.secret — للمفتاح بادئة عامة وجزء سري، موصولان بنقطة (على سبيل المثال cal_abc123.s3cr3t_keymaterial — تستخدم مفاتيح Calendar بادئة قصيرة cal_). تتيح البادئة لـ imatic تحديد المفتاح في القوائم والسجلات؛ والسر هو ما يثبت أنه ملكك.
  • يُعرض مرة واحدة — تُعرض قيمة المفتاح الكاملة فقط لحظة إنشائه. بعد ذلك، تكون البادئة فقط مرئية.
  • النطاقات — كل مفتاح محدود بالإجراءات التي تمنحه إياها. نطاقات Calendar هي slots:read وbookings:read وbookings:write وmcp (النطاق mcp هو ما يحتاجه مفتاح وكيل الذكاء الاصطناعي — انظر MCP لوكلاء الذكاء الاصطناعي). يُرفض أي طلب يتجاوز نطاق المفتاح.
تعامل مع مفاتيح API كأنها كلمات مرور

يُعرض سرّ المفتاح مرة واحدة فقط، عند الإنشاء. انسخه حينها وخزّنه في مدير أسرار أو متغير بيئة — لا في إدارة المصدر، أو لقطة شاشة، أو مستند مشترك أبدًا. إذا تعرّض مفتاح للكشف، أبطله في منطقة المطوّرين وأنشئ بديلًا. يسري الإبطال فورًا.

خطافات الويب​

بدلًا من الاستقصاء عن التغييرات، سجّل رابط خطاف ويب وسترسل imatic حدثًا بـ POST إليه عند حدوث شيء — على سبيل المثال إنشاء حجز في Calendar أو إرسال استجابة في Survey. تدير نقاط نهاية خطافات الويب في منطقة للمطوّرين ← خطافات الويب لكل منتج، حيث يمكنك أيضًا إرسال تسليم اختباري.

يبدو التسليم تقريبًا هكذا:

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 باستخدام سرّ التوقيع لنقطة النهاية لديك، في ترويسة X-Imatic-Signature على نمط Stripe. تحمل الترويسة حقلين: t، وهو ثوانٍ unix-epoch وقت الإرسال، وv1، وهو HMAC الست عشري للسلسلة ${t}.${body} (الطابع الزمني، ثم نقطة حرفية، ثم جسم الطلب الخام بالضبط). للتحقق، قسّم الترويسة، وأعد حساب v1 على t + "." + rawBody بسرّ التوقيع لديك، وقارن في زمن ثابت. ارفض إن لم يتطابقا — واختياريًا ارفض عندما يكون 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 محدودة المعدل لإبقاء المنصة عادلة ومستقرة. إذا تجاوزت الحد، تستجيب الواجهة بـ HTTP 429 Too Many Requests. تراجع وأعد المحاولة — مثاليًا بتراجع أسّي وتشويش — بدلًا من إرهاق نقطة النهاية.

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

معالجة الأخطاء​

تستخدم الأخطاء رموز حالة HTTP القياسية مع جسم JSON يصف ما حدث خطأً. الرموز التي ستراها غالبًا:

  • 400 — كان الطلب مشوّهًا أو فشل في التحقق.
  • 401 — مفتاح API مفقود أو غير صالح.
  • 403 — المفتاح صالح لكنه يفتقر إلى النطاق (أو وصول المؤسسة) لهذا الإجراء.
  • 404 — المورد غير موجود أو غير مرئي لهذا المفتاح.
  • 409 — تعارض، مثل محاولة حجز وقت أُخذ للتو.
  • 429 — محدود المعدل؛ تراجع وأعد المحاولة.
  • 5xx — خطأ من جانب الخادم؛ أعد محاولة الإخفاقات العابرة.

مغلّف خطأ نموذجي:

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

الموارد حسب المنتج​

الاصطلاحات أعلاه مشتركة، لكن كل منتج يكشف عن نقاط نهايته الخاصة. ابدأ من صفحة المطوّرين الخاصة بالمنتج للموارد والمعاملات وأسماء الحقول الدقيقة:

  • Calendar — أنواع الفعاليات، وأوقات التوافر، والحجوزات (الإنشاء وإعادة الجدولة والإلغاء)، والتقويمات، وخطافات الويب، ومفاتيح API، وروابط الفعاليات. أحداث خطافات الويب هي booking.created وbooking.cancelled وbooking.rescheduled وbooking.no_show. انظر Calendar للمطوّرين.
  • Survey — النماذج، والاستجابات، وتجميع الاستجابات، وتوليد النماذج بالذكاء الاصطناعي، وخطافات الويب (form.published وresponse.submitted). انظر Survey للمطوّرين.
  • Voice Portal — الوكلاء، والحملات، وجهات الاتصال، إضافةً إلى تسجيل الأدوات وخادم MCP. انظر الأدوات وMCP للوكلاء.

ذات صلة​