وثائق ⁦API⁩

يتيح لك ⁦Shifton⁩ المهام أتمتة العمل مع المنصة وربطها بخدمات خارجية عبر ⁦API⁩ المفتوح. وتتاح عبر ⁦API⁩ جميع الكيانات الرئيسية — المهام، والعملاء، والموظفون، وقوائم التحقق، والمخزون، ومناطق الخدمة، ومستندات الوثائق المالية، والتقارير — لذا يمكن ربط ⁦Shifton⁩ بأنظمة ⁦HR⁩ وحساب الرواتب والتحليلات لديك، وكذلك بالخدمات الداخلية للشركة.

نُشرت الوثائق في نسختين:

🚀 وثائق جديدة — النسخة الحالية من المرجع ببنية محدَّثة وأحدث الطرق: 👉 https://api2.shifton.com/openapi/
📄 الوثائق القديمة — النسخة السابقة (وما زالت مدعومة للتكاملات القائمة): 👉 https://api2.shifton.com/docs/

ويمكن فتح النسختين مباشرةً من التطبيق — في قسم ⁦Developer⁩، في علامة التبويب نظرة عامة، بزرَّي «وثائق جديدة» و«الوثائق القديمة».

الوثائق متاحة بلغتين. ففي الزاوية العلوية اليمنى من صفحة الوثائق الجديدة يوجد مفتاح تبديل ⁦EN / RU⁩ — وتُحفظ اللغة المختارة.

كيفية الحصول على مفتاح ⁦API⁩

يُنشأ مفتاح ⁦API⁩ في التطبيق نفسه:

افتح قسم ⁦Developer⁩.
انتقل إلى علامة التبويب مفاتيح API («مفاتيح API»).
انقر على «إنشاء مفتاح API».

ما الذي يُملأ عند إنشاء المفتاح

ستُفتح لوحة جانبية إنشاء مفتاح API تتضمن الحقول التالية:

العنوان — اسم المفتاح، وهو حقل إلزامي. سمِّه بحسب الغرض ليتضح لاحقًا ما الذي يجب تعطيله: «التصدير إلى ⁦1C⁩»، «تقارير التحليلات».
تنتهي في — التاريخ الذي يتوقف بعده عمل المفتاح. وإذا تُرك الحقل فارغًا، فلا حد لمدة الصلاحية.
الوصول — نطاق أذونات المفتاح:
وصول كامل (التصرف نيابةً عني) — يعمل المفتاح باسمك وبأذوناتك.
أذونات مقيدة — مجموعة محدودة من الأذونات تختارها بنفسك.

انقر على إضافة لإنشاء المفتاح، أو على إلغاء لإغلاق اللوحة.

📷 *لقطة لوحة إنشاء المفتاح — تُلتقط على بيئة الإنتاج*

ويُنشأ المفتاح لشركة بعينها ويعمل مع بياناتها فقط. ويمكن سحب المفتاح في أي وقت — ويسري السحب فورًا، وستُرجع جميع الطلبات اللاحقة بهذا المفتاح الخطأ ⁦401⁩.

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

المصادقة

تُوقَّع جميع الطلبات إلى ⁦API⁩ بالمفتاح في الترويسة:

Authorization: Bearer {your_API_key}

العنوان الأساسي لـ⁦API⁩:

https://api2.shifton.com/work/1.0.0

ويُرجع الطلب الذي لا يتضمن مفتاحًا ساريًا الرمز ⁦401⁩ والنص ⁦{"message":"Unauthenticated."}⁩.

الطلب الأول

مثلًا، للحصول على قائمة موظفي الشركة (ضع معرّف شركتك بدلًا من ⁦{companyId}⁩):

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

والأمر نفسه عبر ⁦curl⁩:

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

ويظهر معرّف الشركة في شريط عنوان التطبيق: ⁦app.shifton.com/c/8397/...⁩ — أي الرقم الذي يلي ⁦/c/⁩.

ما المتاح عبر ⁦API⁩

يغطي المرجع أكثر من ⁦360⁩ طريقة. والأقسام الأساسية للخدمة الميدانية هي:

المهام — ⁦/companies/{companyId}/tasks⁩: الإنشاء، والتعديل، والحالات، وملفات المهام.
قائمة المهام ⁦(To Do)⁩ — ⁦/companies/{companyId}/todo⁩.
العملاء — ⁦/companies/{companyId}/clients⁩، وكذلك عناوين العملاء وحقولهم المخصصة.
قوائم التحقق — ⁦/companies/{companyId}/checklists⁩.
مناطق الخدمة — ⁦/companies/{companyId}/tasks/service-areas⁩.
المهارات — ⁦/companies/{companyId}/skills⁩.
الموظفون — ⁦/companies/{companyId}/employees⁩: الإضافة، والتحرير، والفصل، والاستعادة.
المخزون — العناصر، والفئات، والمجموعات، والأرصدة في المستودعات.
الوثائق المالية — عروض الأسعار، وأوامر العمل، والفواتير، والإيصالات، وعدّادات المستندات والشعار.
التقارير — تصدير بيانات العمل والحضور.

وإضافةً إلى ذلك، تتاح الجداول والورديات، والإجازات وطلبات التغيّب، والحضور، والفوترة وفوترة ⁦SMS⁩، والإشعارات والوحدات.

⁦Webhooks⁩

إذا كنت بحاجة إلى تلقي الأحداث لحظة وقوعها بدلًا من إرسال طلبات منتظمة إلى ⁦API⁩، فاستخدم ⁦webhooks⁩ — علامة التبويب ⁦Webhooks⁩ في قسم ⁦Developer⁩. فسيرسل ⁦Shifton⁩ بنفسه طلبًا إلى عنوانك عند وقوع الحدث المطلوب؛ وتُرجع قائمةَ الأحداث المدعومة طريقةٌ مستقلة.

رموز الأخطاء

يستخدم ⁦API⁩ الخاص بـ⁦Shifton⁩ رموز حالة ⁦HTTP⁩ القياسية:

⁦200⁩ — نُفِّذ الطلب بنجاح.
⁦201⁩ — أُنشئ الكائن بنجاح.
⁦400⁩ — معايير الطلب غير صحيحة.
⁦401⁩ — خطأ في المصادقة: المفتاح غير مُرسَل أو غير صالح أو مسحوب.
⁦403⁩ — الوصول ممنوع.
⁦404⁩ — المورد غير موجود (وغالبًا ما يكون السبب خطأً مطبعيًا في عنوان الطريقة).
⁦500⁩ — خطأ في الخادم.

نصائح للاستخدام

للتكاملات الجديدة استخدم الوثائق الجديدة — أما القديمة فقد تُركت للتكاملات العاملة بالفعل.
ولاختبار الطلبات من المريح استخدام بوستمان أو ⁦curl⁩ — فهما يتيحان رؤية الاستجابة دون كتابة سطر واحد من التعليمات البرمجية.
لا تحفظ المفتاح بصورة مكشوفة في التعليمات البرمجية ولا تُفصح عنه لأطراف ثالثة: فالمفتاح يمنح الوصول إلى بيانات الشركة.
التزم بـقيود تواتر الطلبات ⁦(rate limits)⁩ — فتجاوزها قد يؤدي إلى حظر مؤقت للوصول إلى ⁦API⁩.

الأسئلة الشائعة

سؤال: من أين أحصل على مفتاح ⁦API⁩؟ الإجابة: في التطبيق: قسم ⁦Developer⁩ ← علامة التبويب مفاتيح API ← زر «إنشاء مفتاح API». ويُصدر المفتاح للشركة الحالية.

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

سؤال: كيف أسحب المفتاح إذا وقع في أيدٍ غير مناسبة؟ الإجابة: احذفه في علامة التبويب مفاتيح API. ويسري السحب فورًا: فجميع الطلبات بهذا المفتاح ستبدأ على الفور بإرجاع ⁦401⁩.

سؤال: ما الفرق بين «⁦Full access⁩» و«⁦Restricted permissions⁩»؟ الإجابة: يمنح وصول كامل (التصرف نيابةً عني) المفتاحَ الأذونات نفسها التي لديك. أما أذونات مقيدة فتتيح منح المفتاح مجموعة الأذونات المختارة فقط — وهذا أكثر أمانًا للتكامل الذي لا يحتاج إلا إلى جزء من البيانات.

سؤال: هل يمكن تحديد مدة صلاحية للمفتاح؟ الإجابة: نعم، عبر حقل تنتهي في عند الإنشاء. وإذا لم يُملأ، فسيكون المفتاح غير محدود المدة.

سؤال: هل يعمل مفتاح واحد لعدة شركات؟ الإجابة: لا. فالمفتاح مرتبط بالشركة التي أُنشئ فيها، ويعمل مع بياناتها فقط. ولشركة أخرى أنشئ مفتاحًا مستقلًا.

سؤال: ما العنوان الأساسي لـ⁦API⁩؟ الإجابة: ⁦https://api2.shifton.com/work/1.0.0⁩. ثم يأتي مسار الطريقة، مثلًا ⁦/companies/{companyId}/tasks⁩.

سؤال: من أين أحصل على معرّف الشركة للطلبات؟ الإجابة: إنه موجود في شريط عنوان التطبيق مباشرةً بعد ⁦/c/⁩ — فمثلًا في ⁦app.shifton.com/c/8397/tasks⁩ يساوي معرّف الشركة ⁦8397⁩.

سؤال: أي نسخة من الوثائق أستخدم؟ الإجابة: للتكاملات الجديدة — الجديدة (⁦api2.shifton.com/openapi⁩). أما القديمة (⁦api2.shifton.com/docs⁩) فمدعومة للتكاملات القائمة.

سؤال: هل توجد وثائق باللغة الروسية؟ الإجابة: نعم. ففي صفحة الوثائق الجديدة يوجد في الزاوية العلوية اليمنى مفتاح التبديل ⁦EN / RU⁩.

سؤال: بأي أداة أختبر الطلبات إلى ⁦API⁩؟ الإجابة: الأنسب هو بوستمان أو ⁦curl⁩ — فهما يتيحان إرسال الطلبات ومطالعة الاستجابات دون كتابة تعليمات برمجية.

سؤال: لماذا يأتي الخطأ ⁦401⁩ رغم أنني نسخت المفتاح؟ الإجابة: تحقق من أن المفتاح يُرسَل في ترويسة ⁦Authorization⁩ مسبوقًا بالكلمة ⁦Bearer⁩، ومن أن المفتاح غير مسحوب ولم تنتهِ مدة صلاحيته.

سؤال: لماذا يأتي الخطأ ⁦404⁩؟ الإجابة: غالبًا ما يكون العنوان مختلطًا: فالجزء الأساسي يجب أن يكون ⁦https://api2.shifton.com/work/1.0.0⁩، وفي مسار الطريقة ⁦{companyId}⁩ الصحيح.

سؤال: ما الذي يمكن أتمتته عبر ⁦API⁩؟ الإجابة: إنشاء المهام وتعديلها، والعمل مع العملاء وعناوينهم، وقوائم التحقق، ومناطق الخدمة، والمهارات، والموظفين، والمخزون، ومستندات الوثائق المالية وتصدير التقارير، وكذلك الجداول والورديات والإجازات.

سؤال: هل يمكن تلقي الأحداث من ⁦Shifton⁩ بدلًا من استعلام ⁦API⁩؟ الإجابة: نعم، ولهذا توجد ⁦webhooks⁩ — علامة التبويب ⁦Webhooks⁩ في قسم ⁦Developer⁩.

سؤال: هل يؤثر تغيير كلمة المرور في عمل التكامل؟ الإجابة: لا. فالتكاملات تعمل بمفتاح ⁦API⁩ وليس بكلمة مرور الحساب.