نظرة عامة على API
تجدول واجهة API العامة من شارك المنشورات، وتدير القنوات، وترفع الوسائط، وتسحب التحليلات عبر HTTP. ومعظم ما تفعله في التقويم تستطيع فعله من سكربت.
العنوان الأساسي
Section titled “العنوان الأساسي”كل عملية في هذه الصفحات تقع تحت بادئة واحدة:
https://dash.sharek.app/api/public/v1ومن ثم فسرد قنواتك هو GET إلى https://dash.sharek.app/api/public/v1/integrations.
المصطلحات
Section titled “المصطلحات”ومعرفان يتكرران باستمرار ويسهل الخلط بينهما:
- معرف التكامل يحدد قناة مربوطة. تحصل عليه من سرد القنوات، أو من نسخ معرف القناة في قائمة القناة داخل التطبيق.
- معرف المنشور وgroup يحددان منشورًا مجدولًا. فاستدعاء واحد لـ إنشاء منشور عبر ثلاث قنوات ينشئ ثلاثة منشورات، لكل منها معرف وgroup خاصان به. وردود المنشور تتشارك قيمة group الخاصة به، وهي ما تأخذه عملية حذف مجموعة منشورات.
المصادقة
Section titled “المصادقة”أرسل مفتاحك في ترويسة Authorization بلا بادئة مخطط:
curl -H "Authorization: your-api-key" \ https://dash.sharek.app/api/public/v1/is-connectedوالاستدعاء الناجح يجيب {"connected": true}. ومن أين يأتي المفتاح، وما هي رموز OAuth
التي تبدأ بـ pos_، وكيف يبدو كل إخفاق، كل ذلك في
المصادقة.
حد الطلبات
Section titled “حد الطلبات”عملية واحدة مقيدة: إنشاء منشور، بحد 100 طلب في الساعة لكل مؤسسة. وكل ما عداها بلا قيد.
وهي 100 طلب، لا 100 منشور. فاستدعاء إنشاء واحد يحمل قنوات كثيرة ومنشورات كثيرة، لذا
اجمعها في دفعة بدل التكرار في حلقة حين تجدول بالجملة. وتجاوز الحد يعيد 429.
أعراف الطلبات
Section titled “أعراف الطلبات”- التواريخ بتوقيت UTC، بصيغة ISO 8601، مثل
2026-09-01T10:00:00.000Z. - أجسام JSON محدودة بنحو 100 kb. وهذا صغير عن قصد: فلا مكان للوسائط داخل جسم الطلب. ارفعها أولًا بـ رفع ملف أو الرفع من عنوان، ثم أشر إلى ما تعيده هاتان العمليتان.
- API للاستخدام من جهة الخادم. فطلبات المتصفح عابرة الأصل مرفوضة: طلب الفحص المسبق من أصل غير ذي صلة يعود بلا ترويسة أصل مسموح. استدعها من خادمك الخلفي، أو من سكربت، أو من أداة CLI، ولا تضع مفتاحك في جهة العميل.
أشكال الأخطاء
Section titled “أشكال الأخطاء”يعيد شارك خمسة أشكال مختلفة من أخطاء JSON بحسب الطبقة التي رفضت الطلب. عالجها كلها إن كنت تكتب عميلًا لـ API.
| المصدر | الحالة | الشكل |
|---|---|---|
| أخطاء المتحكم | 400, 401, 404, 500 | {"msg": "..."} |
| التحقق من المنشور عند الإنشاء | 400 | {"statusCode": 400, "provider": "...", "name": "...", "message": "..."} |
| الحصة أو الاشتراك | 402 | {"statusCode": 402, "message": "...", "url": "...", "section": "...", "resetsAt": "..."} |
| التحقق من الحقول | 400 | {"statusCode": 400, "message": ["..."], "error": "Bad Request"} |
| البحث عن العناصر وفحوص الخدمة والتقييد | 400, 404, 406, 422, 429, 500 | {"statusCode": 404, "message": "Post not found", "error": "Not Found"} |
وفي الشكل الأخير تكون message نصًا واحدًا، وقد يغيب error: فالوسائط غير الموجودة تجيب
{"statusCode": 404, "message": "Media not found"}، والتقييد يجيب 429 ومعه
"message": "ThrottlerException: Too Many Requests"، وخطأ الخادم غير المتوقع يجيب 500
ومعه "message": "Internal server error".
وعملية تحديث إعدادات المنشور تجري الفحوص نفسها لكنها تجيب بالشكل
الأخير، واسم القناة في بداية message.
وشكل 402 هو الجدير بمعالجة خاصة. فهو يعني أن المؤسسة بلغت حد خطتها لا أنها أرسلت طلبًا
غير صالح، وurl فيه يشير إلى موضع حل المشكلة.
إلى أين بعد ذلك
Section titled “إلى أين بعد ذلك”- المصادقة للحصول على مفتاح وإجراء أول استدعاء.
- تطبيقات OAuth إن كنت تبني منتجًا يتصرف نيابةً عن حسابات شارك أخرى.
- جلب الحساب الحالي لترى بمن تتصرف بيانات الاعتماد نيابةً عنه: المؤسسة، ومع رمز OAuth الشخص أيضًا.
- إنشاء منشور هي العملية التي يبحث عنها معظم من يبنون على API، وهي صاحبة أكبر جسم طلب.
- بدء ربط قناة لتتيح لأحدهم ربط قناة من داخل منتجك.
- سرد الإشعارات لتلتقط إخفاقات النشر والقنوات التي تحتاج إعادة ربط.
- الأتمتة بـ n8n إن كانت عقدة في سير عمل ستوفر عليك كتابة عميل API من أساسه.