واجهة البرمجة العامة

تتيح واجهة البرمجة العامة لبرامجك الخاصة أن تتحدّث مع Service Suite: برنامج محاسبة يسحب الفواتير، بوابة عملاء تُنشئ تدخّلًا، لوحة متابعة ترصد حالة أصولك.

إنها واجهة منتج: تتعامل مع العملاء والمواقع والأصول وأوامر الخدمة والعقود والمخزون والفواتير. ولست بحاجة أبدًا لمعرفة كيف بُني Service Suite داخليًا.

شاشة المفاتيح. يعمل كل مفتاح دائمًا بصفة مستخدم محدّد.

فيمَ تستخدم هذا

• إبقاء العملاء والمواقع متوافقة مع نظام إدارتك الحالي.
• السماح لنظام آخر بإنشاء أوامر خدمة — أداة مراقبة، نموذج ويب، بوابة عملاء.
• قراءة الفواتير ومستويات المخزون لأغراض التقارير.
• إشعار نظام خارجي فور انتهاء تدخّل.

من يستطيع استخدام هذا

الدور	ما يفعله
المسؤول	ينشئ المفاتيح ويمنح الصلاحيات ويلغي المفاتيح
مطوّرك أو مورّدك	يستخدم المفتاح للربط

المتطلبات: صلاحية مسؤول في Service Suite، وشخص قادر على بناء الربط. لا حاجة إلى ترخيص أو وحدة إضافية.

بداية سريعة

العنوان الأساسي	https://<عنوان-خدمتك>/api/v1/
المواصفة	/api/v1/openapi.json — OpenAPI 3.1
صفحة التوثيق	/api/docs

curl https://<عنوان-خدمتك>/api/v1/me \
  -H "Authorization: Bearer <API_KEY>"

/me هو فحص السلامة: يثبت أن المفتاح يعمل ويُظهر بالضبط ما يُسمح له به.

{
  "data": {
    "credential": {
      "name": "المحاسبة — مزامنة ليلية",
      "prefix": "a1b2c3d4",
      "scopes": ["customers:read", "invoices:read"],
      "expires_at": null
    },
    "acting_as": { "id": 42, "name": "ربط المحاسبة" },
    "api_version": "v1"
  }
}

إنشاء مفتاح

1. اذهب إلى الإعدادات ← واجهة البرمجة العامة ← مفتاح API جديد.

2. أعطِ المفتاح اسمًا يوضّح الغرض منه. يظهر هذا الاسم في سجل الوصول.

3. اختر باسم أي مستخدم يعمل المفتاح. هذا هو حدّ الصلاحيات الحقيقي — انظر أدناه.

4. حدِّد الصلاحيات (scopes) التي يحتاجها الربط، ولا شيء أكثر.

5. اضبط عند الحاجة تاريخ انتهاء ونطاقات IP مسموحًا بها.

6. احفظ. يُعرض السر مرة واحدة. انسخه فورًا إلى خزنة كلمات المرور لديك.

لا يمكن استرجاع السر لاحقًا

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

المفتاح ليس صلاحية

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

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

الصلاحيات (scopes)

الصلاحية	ما تفتحه
customers:read / customers:write	العملاء
locations:read / locations:write	المواقع
assets:read / assets:write	الأصول والمعدات
service_orders:read / service_orders:write	أوامر الخدمة
contracts:read	عقود الصيانة
stock:read	المخزون
invoices:read	الفواتير
reports:read	بيانات التقارير
webhooks:manage	إدارة الـ Webhooks

المخزون والفواتير للقراءة فقط في الإصدار v1. أما القيود المحاسبية وحركات المخزون فتتم داخل Service Suite نفسه، لا عبر الواجهة.

ما يمكنك قراءته وتعديله

المورد	قراءة	إنشاء	تعديل	أرشفة
customers	✅	✅	✅	✅
locations	✅	—	✅	—
assets	✅	✅	✅	✅
service-orders	✅	✅	✅	—
contracts	✅	—	—	—
stock	✅	—	—	—
invoices	✅	—	—	—

GET    /api/v1/<المورد>              قائمة
GET    /api/v1/<المورد>/<id>         سجل واحد
POST   /api/v1/<المورد>              إنشاء
PATCH  /api/v1/<المورد>/<id>         تعديل
DELETE /api/v1/<المورد>/<id>         أرشفة (وليس حذفًا نهائيًا أبدًا)

DELETE يؤرشف. لا يُحذف شيء نهائيًا عبر الواجهة أبدًا.

الحقول تُتاح عن قصد

يعيد كل مورد قائمة ثابتة من الحقول. الحقل الجديد في Service Suite لا يظهر في الواجهة من تلقاء نفسه — فذلك قرار مقصود لكل حقل، وهو الفرق بين واجهة برمجة وتفريغ لقاعدة بيانات عبر HTTP.

الترقيم والتصفية والترتيب

curl "https://<عنوان-خدمتك>/api/v1/assets?customer_id=57&page=2&page_size=100&sort=-write_date" \
  -H "Authorization: Bearer <API_KEY>"

المعامل	الافتراضي	الأقصى
page	1	—
page_size	50	200

إن طلبت أكثر من 200 حصلت على 200 — لا على رسالة خطأ.

الترتيب عبر sort، بعدة حقول مفصولة بفواصل، مع - في المقدّمة للترتيب التنازلي. والتصفية بأسماء مرشِّحات المورد؛ ويوجد updated_since على كل مورد وهو ما تحتاجه للمزامنة التدريجية.

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

إعادة المحاولة بأمان

أرسل Idempotency-Key خاصًا بك مع كل POST:

curl -X POST https://<عنوان-خدمتك>/api/v1/service-orders \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Idempotency-Key: <قيمة_فريدة_لكل_طلب>" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": 57, "location_id": 112, "description": "صيانة سنوية"}'

إن انقطع الاتصال وأعدت المحاولة بالقيمة نفسها، حصلت على النتيجة الأصلية بدل أمر خدمة ثانٍ. وبدون هذه الترويسة يكون الطلب المكرَّر طلبًا ثانيًا حقيقيًا.

يعيد كل طلب أيضًا X-Request-Id. اذكره عند الإبلاغ عن مشكلة — به يُعثر على طلبك في السجل.

معدّل الطلبات

النوع	في الدقيقة
قراءة	600
كتابة	120
إدارة الـ Webhooks	60
محاولات دخول فاشلة	20

يعمل العدّاد لكل مفتاح على حدة، فلا يستهلك ربط مزدحم رصيد ربط آخر. وعند التجاوز تحصل على 429 مع ترويسة Retry-After. احترمها وأعد المحاولة بمهلة متصاعدة.

الأخطاء

الرمز	المعنى	ما تفعله
400	معامل أو حقل غير صالح	صحّح الطلب؛ تذكر الاستجابة اسم الحقل
401	المفتاح مفقود أو خاطئ أو منتهٍ أو ملغى	تحقّق من المفتاح
403	المفتاح تنقصه الصلاحية، أو المستخدم تنقصه الأحقّية	امنح الصلاحية، أو عدّل صلاحيات المستخدم
404	غير موجود، أو خارج نطاق المستخدم	تحقّق من المعرّف ومن الصلاحيات
409	تعارض — مثل إعادة استخدام Idempotency-Key بمحتوى مختلف	استخدم قيمة جديدة
429	طلبات كثيرة جدًا	انتظر وأعد المحاولة

الرمز 403 الناتج عن نقص صلاحية والرمز 403 الناتج عن نقص أحقّية المستخدم يستدعيان حلَّين مختلفين. وتذكر الاستجابة أيّهما.

الـ Webhooks

إمكانية تُفعّلها بنفسك

الـ Webhooks مدعومة بالكامل، لكن لا شيء منها مهيّأ مسبقًا. فعنوان الاستقبال تنشئه وتديره لكل بيئة على حدة. وما لم تنشئ واحدًا، لا يرسل Service Suite أي شيء إلى الخارج.

بدل الاستعلام المتكرّر، دع Service Suite يُشعرك.

الحدث	متى
service_order.created	أُنشئ أمر خدمة
service_order.updated	عُدِّل أمر خدمة
service_order.status_changed	تغيّرت الحالة
service_order.completed	انتهى التدخّل
asset.created / asset.updated	أُنشئ أصل أو عُدِّل
contract.created	أُنشئ عقد صيانة
invoice.posted	رُحِّلت فاتورة

يحمل كل تسليم توقيع HMAC-SHA256. تحقّق منه قبل استخدام المحتوى — به تعرف أن الإشعار جاء فعلًا من بيئتك. تتم عمليات التسليم في الخلفية وتُعاد المحاولة بمهلة متصاعدة عند الفشل.

يجب أن يكون عنوان الاستقبال لديك متاحًا للعموم. أما العناوين على شبكة خاصة فتُرفض.

الـ Webhooks تتطلّب تخزينًا مشفَّرًا

يجب أن يبقى مفتاح التوقيع قابلًا للقراءة كي يوقّع، فلا يمكن تجزئته. لذا يُحفظ مشفَّرًا، بمفتاح يعيش خارج قاعدة البيانات. وإن لم يكن هذا التشفير متاحًا في بيئة ما، يُرفض الـ webhook بدل حفظه دون حماية.

الفصل بين البيئات

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

التدقيق

يُسجَّل كل طلب: الوقت والمفتاح والأسلوب والمورد ورمز الاستجابة والمدة ومؤشّر للمصدر. ولا يُسجَّل أبدًا محتوى الطلبات ولا المفاتيح ولا الترويسات. بهذا يبقى السجل مفيدًا لتحليل مشكلة دون أن يصبح هو نفسه نسخة ثانية من بياناتك.

القيود المعروفة

مذكورة لا مسكوت عنها.

• المخزون والفواتير للقراءة فقط في الإصدار v1. لا يمكن إنشاؤها أو تعديلها عبر الواجهة البرمجية.
• الفنّيون والفرق والمشاريع والساعات ليس لها مورد خاص في v1.
• للواجهة إصدار واحد هو v1. أي تغيير قد يكسر التكاملات القائمة يذهب إلى إصدار لاحق لا إلى هذا الإصدار.

ممارسات جيدة

• مفتاح واحد لكل ربط، لا مفتاح مشترك أبدًا. بهذا تلغي واحدًا دون كسر البقية.
• امنح الصلاحيات التي يستخدمها الربط فقط. ابدأ بالقراءة وحدها.
• استخدم Idempotency-Key دائمًا عند الإنشاء.
• زامِن تدريجيًا عبر updated_since بدل جلب كل شيء في كل مرة.
• احفظ السر في خزنة، لا في الشيفرة المصدرية ولا في ملف إعداد يدخل نظام إصدارات.
• اضبط تاريخ انتهاء لمفاتيح الأطراف الخارجية.

الخطوة التالية

• الصلاحيات والأمان — أي مستخدم يصبح المفتاح
• التكاملات — روابط جاهزة
• الأتمتة — الأتمتة دون برمجة
• تسجيل الدخول عبر Microsoft أو Google