# REST API


# REST API

تأتي منتجات imatic مزوّدةً بواجهات REST API يمكنك أتمتتها من كودك الخاص. الاصطلاحات في هذه الصفحة — المصادقة، ومفاتيح API، وتوقيع خطافات الويب، وترقيم الصفحات، وحدود المعدل، والأخطاء — هي نفسها عبر المنتجات. ما يختلف هو شكل عنوان URL و**الموارد** التي يكشفها كل منتج: يستخدم Calendar مسارات `/v1` مُصدَّرة الإصدار، بينما يستخدم Survey نقاط نهاية بأسلوب الفعل `POST`. توثّق صفحة المطوّرين الخاصة بكل منتج سطحه الدقيق.

:::note[الأمثلة توضيحية]

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

:::

## المصادقة

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

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

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

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

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

```bash
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 لوكلاء الذكاء الاصطناعي](./mcp)). يُرفض أي طلب يتجاوز نطاق المفتاح.

:::danger[تعامل مع مفاتيح API كأنها كلمات مرور]

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

:::

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

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

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

```http
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` أقدم من بضع دقائق للحماية من إعادة التشغيل.

```js
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);
}
```

:::note[المخطط الدقيق لكل منتج]

المخطط `t=…,v1=…` أعلاه خاص بـ Calendar. أكّد اسم الترويسة وحقولها والسلسلة الموقّعة على صفحة المطوّرين لكل منتج قبل أن تشحن مُتحقِّقًا.

:::

:::tip[رُدّ بسرعة، عالِج لاحقًا]

أعِد `2xx` بسرعة للإقرار بالاستلام، ثم نفّذ أي عمل بطيء بشكل غير متزامن. إذا كانت نقطة النهاية لديك بطيئة أو تُخطئ، فقد تُعاد عمليات التسليم.

:::

## ترقيم الصفحات

تُرجِع نقاط نهاية السرد النتائج في صفحات حتى لا يضطر استدعاء واحد أبدًا إلى تحميل كل شيء. مرّر معاملات ترقيم الصفحات على الطلب واقرأ بيانات ترقيم الصفحات على الاستجابة لجلب الصفحة التالية.

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

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

استمر في طلب الصفحة التالية حتى لا تبقى نتائج أخرى.

## تحديد المعدل

مفاتيح API محدودة المعدل لإبقاء المنصة عادلة ومستقرة. إذا تجاوزت الحد، تستجيب الواجهة بـ HTTP `429 Too Many Requests`. تراجع وأعد المحاولة — مثاليًا بتراجع أسّي وتشويش — بدلًا من إرهاق نقطة النهاية.

```json
{
  "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`** — خطأ من جانب الخادم؛ أعد محاولة الإخفاقات العابرة.

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

```json
{
  "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 للمطوّرين](/calendar/developers).
- **Survey** — النماذج، والاستجابات، وتجميع الاستجابات، وتوليد النماذج بالذكاء الاصطناعي، وخطافات الويب (`form.published` و`response.submitted`). انظر [Survey للمطوّرين](/survey/developers).
- **Voice Portal** — الوكلاء، والحملات، وجهات الاتصال، إضافةً إلى تسجيل الأدوات وخادم MCP. انظر [الأدوات وMCP للوكلاء](/voice/agents/tools-mcp).

## ذات صلة

- [نظرة عامة على المنصة](./overview) — الحسابات، والمؤسسات، والمفاهيم المشتركة.
- [MCP لوكلاء الذكاء الاصطناعي](./mcp) — دع مساعدي الذكاء الاصطناعي يستدعون هذه الموارد نيابةً عنك.
- [Calendar للمطوّرين](/calendar/developers) — REST API وخطافات الويب الخاصة بـ Calendar.
- [Survey للمطوّرين](/survey/developers) — واجهة Survey وخطافات الويب وأدوات MCP.