تخطَّ إلى المحتوى

نظرة عامة على API

تجدول واجهة API العامة من شارك المنشورات، وتدير القنوات، وترفع الوسائط، وتسحب التحليلات عبر HTTP. ومعظم ما تفعله في التقويم تستطيع فعله من سكربت.

كل عملية في هذه الصفحات تقع تحت بادئة واحدة:

https://dash.sharek.app/api/public/v1

ومن ثم فسرد قنواتك هو GET إلى https://dash.sharek.app/api/public/v1/integrations.

ومعرفان يتكرران باستمرار ويسهل الخلط بينهما:

  • معرف التكامل يحدد قناة مربوطة. تحصل عليه من سرد القنوات، أو من نسخ معرف القناة في قائمة القناة داخل التطبيق.
  • معرف المنشور وgroup يحددان منشورًا مجدولًا. فاستدعاء واحد لـ إنشاء منشور عبر ثلاث قنوات ينشئ ثلاثة منشورات، لكل منها معرف وgroup خاصان به. وردود المنشور تتشارك قيمة group الخاصة به، وهي ما تأخذه عملية حذف مجموعة منشورات.

أرسل مفتاحك في ترويسة Authorization بلا بادئة مخطط:

Terminal window
curl -H "Authorization: your-api-key" \
https://dash.sharek.app/api/public/v1/is-connected

والاستدعاء الناجح يجيب {"connected": true}. ومن أين يأتي المفتاح، وما هي رموز OAuth التي تبدأ بـ pos_، وكيف يبدو كل إخفاق، كل ذلك في المصادقة.

عملية واحدة مقيدة: إنشاء منشور، بحد 100 طلب في الساعة لكل مؤسسة. وكل ما عداها بلا قيد.

وهي 100 طلب، لا 100 منشور. فاستدعاء إنشاء واحد يحمل قنوات كثيرة ومنشورات كثيرة، لذا اجمعها في دفعة بدل التكرار في حلقة حين تجدول بالجملة. وتجاوز الحد يعيد 429.

  • التواريخ بتوقيت UTC، بصيغة ISO 8601، مثل 2026-09-01T10:00:00.000Z.
  • أجسام JSON محدودة بنحو 100 kb. وهذا صغير عن قصد: فلا مكان للوسائط داخل جسم الطلب. ارفعها أولًا بـ رفع ملف أو الرفع من عنوان، ثم أشر إلى ما تعيده هاتان العمليتان.
  • API للاستخدام من جهة الخادم. فطلبات المتصفح عابرة الأصل مرفوضة: طلب الفحص المسبق من أصل غير ذي صلة يعود بلا ترويسة أصل مسموح. استدعها من خادمك الخلفي، أو من سكربت، أو من أداة CLI، ولا تضع مفتاحك في جهة العميل.

يعيد شارك خمسة أشكال مختلفة من أخطاء 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 فيه يشير إلى موضع حل المشكلة.

  • المصادقة للحصول على مفتاح وإجراء أول استدعاء.
  • تطبيقات OAuth إن كنت تبني منتجًا يتصرف نيابةً عن حسابات شارك أخرى.
  • جلب الحساب الحالي لترى بمن تتصرف بيانات الاعتماد نيابةً عنه: المؤسسة، ومع رمز OAuth الشخص أيضًا.
  • إنشاء منشور هي العملية التي يبحث عنها معظم من يبنون على API، وهي صاحبة أكبر جسم طلب.
  • بدء ربط قناة لتتيح لأحدهم ربط قناة من داخل منتجك.
  • سرد الإشعارات لتلتقط إخفاقات النشر والقنوات التي تحتاج إعادة ربط.
  • الأتمتة بـ n8n إن كانت عقدة في سير عمل ستوفر عليك كتابة عميل API من أساسه.