الانتقال إلى المحتوى الرئيسي

عنوان الإنتاج وأول طلب

سجّل الدخول إلى التطبيق على https://app.sorank.com. تُدار المفاتيح على https://app.sorank.com/settings/api، والعنوان الأساسي لطلبات REST هو https://app.sorank.com/api/public/v1. لا تحتاج إلى إنشاء خادم API.
  1. افتح الإعدادات ← الوصول إلى API وأنشئ مفتاحًا باسم وموقع واحد على الأقل وصلاحية عرض المواقع (profiles:read) وتاريخ انتهاء. أضف عرض الحصص (quotas:read) للطلب الثاني.
  2. انسخ المفتاح الكامل فورًا؛ يظهر مرة واحدة فقط. البادئة المعروضة لاحقًا لا تكفي للمصادقة.
  3. اختر مثالًا. في cURL أدخل المفتاح عند المطالبة به. في JavaScript أو Go اضبط SORANK_API_KEY في بيئة عملية الخادم. تتضمن علامة تبويب HTML خادم Node.js محليًا: شغّله والمفتاح في بيئته ثم افتح http://127.0.0.1:3100. لا تضع المفتاح داخل HTML أو JavaScript في المتصفح. أضف مصادقة تطبيقك قبل استخدام هذا النمط خارج العرض المحلي.
تضم الاستجابة المواقع المسموح بها في data. استخدم قيمة data[].id بوصفها profile_id للطلبات اللاحقة. إذا كانت القائمة فارغة فتحقق من المواقع المحددة وصلاحياتك. تقرأ أمثلة cURL وJavaScript وGo حصة أول ملف شخصي أيضًا مع quotas:read. يوضح مرجع API العام في تنقل المطورين المسارات والصلاحيات والاستجابات.

المصادقة

أنشئ مفتاح API شخصيًا من الإعدادات ← الوصول إلى API للبرامج النصية، أو فوّض عميل OAuth باستخدام PKCE S256. حدّد الملفات الشخصية والنطاقات اللازمة فقط. أرسل الرمز بترويسة Bearer. لا تصلح ملفات تعريف الارتباط أو رموز Supabase لهذه الواجهة. للتطبيقات التي تعمل نيابة عن المستخدم، ابدأ من https://app.sorank.com/.well-known/oauth-protected-resource/api/public/v1 وhttps://app.sorank.com/.well-known/oauth-authorization-server. اكتشف نقاط OAuth المعلنة وسجّل عميلًا عامًا عند الحاجة واستخدم authorization code مع PKCE S256 والنطاقات اللازمة والمورد المحدد https://app.sorank.com/api/public/v1. رمز OAuth الخاص بـMCP لا يصلح لطلبات REST.

الأذونات والحصة

افحص getQuotas قبل الإنشاء. يتطلب المثال profiles:read وquotas:read وcalendar:read وcalendar:write وarticles:read وarticles:generate وarticles:publish. ويتطلب إنشاء التقويم صلاحيات الإنشاء والنشر أيضًا. تتشارك الواجهة والتطبيق وMCP الحصة نفسها؛ لا تزيدها المفاتيح الإضافية. صلاحيات القراءة عرض المنتجات (products:read) وعرض التحليلات (analytics:read) وعرض الظهور في الذكاء الاصطناعي (geo:read) وعرض الإعدادات (settings:read) لا تستهلك الحصة أبدًا. أما تعديل الإعدادات (settings:write) فتغيّر الإعدادات نفسها التي يغيّرها التطبيق؛ امنحها فقط عندما يلزم أن يغيّرها تكامل ما.

التحقق من الأهلية

تتوفر واجهة API بعد إكمال الإعداد الأولي في Sorank وعندما يكون للموقع اشتراك صالح. يستخدم متعاون الوكالة اشتراك مالك الموقع. تتحقق Sorank من ذلك عند إنشاء مفتاح أو الموافقة على اتصال OAuth، ثم مع كل طلب.
  • يعيد listProfiles المواقع المؤهلة فقط.
  • يعيد الإعداد الأولي غير المكتمل 403 onboarding_required.
  • يعيد الموقع الذي لا يملك اشتراكًا صالحًا 402 subscription_required، مع details.reason (paused أو past_due أو incomplete أو inactive) عند معرفته.
أكمل الإعداد الأولي أو حدّث الاشتراك في الإعدادات ← الفوترة. يعمل مفتاحك الحالي مجددًا بدءًا من الطلب التالي.

قراءة المنتجات والتحليلات والظهور في الذكاء الاصطناعي والإعدادات

تعيد هذه القراءات ما يعرضه لك تطبيق Sorank. ولا تبدأ أبدًا تحليلًا أو مزامنة أو إنشاء محتوى.
  • المنتجات (products:read): يتصفح listProducts كتالوج المنتجات بمؤشر. بعد 409 product_catalog_cursor_stale ابدأ من الصفحة الأولى.
  • التحليلات (analytics:read): الأداء والاستعلامات والصفحات والدول والأجهزة من Search Console، وزيارات Google Analytics القادمة من مساعدي الذكاء الاصطناعي. الحقلان start وend (YYYY-MM-DD) إلزاميان. كل استدعاء يقرأ من Google مباشرة وله حد معدل أقل. اربط Google في Sorank أولًا؛ وإلا تتلقى 409 gsc_not_connected أو 409 ga_not_connected، و403 google_access_lost إذا فُقد الوصول.
  • الظهور في الذكاء الاصطناعي (geo:read): إحصاءات GEO وتطور الإشارات والجدول الزمني للاستشهادات والمصادر المستشهِدة والمنافسون المذكورون في تحليل.
  • الإعدادات (settings:read): يعيد getSettings الموقع وملخص النشاط مع revision الخاص به والمنافسين وإعدادات المقالات الافتراضية والمرئيات وقناة YouTube.

تغيير الإعدادات

باستخدام settings:write يمكنك تغيير اسم النشاط ولون العلامة والسوق، واستبدال ملخص النشاط وقائمة المنافسين، وتغيير الإعدادات الافتراضية لمقالات التقويم ووضع الصور وصور الغلاف، وربط قناة YouTube أو إيقافها مؤقتًا أو فصلها. لا يمكن تغيير عنوان الموقع عبر واجهة API (400 field_not_writable). يتطلب كل تغيير Idempotency-Key. تتضمن الاستجابة الإعدادات الناتجة وإيصالًا وقائمة effects بالعمليات التي بدأت في الخلفية، كما في التطبيق: geo_questions_regeneration_queued أو backlink_refresh_queued أو calendar_slots_shifted أو image_gallery_analysis_queued أو youtube_sync_queued أو youtube_purge_queued. لاستبدال ملخص النشاط، أرسل expected_revision المقروء من getSettings. إذا تغيّر الملخص في الأثناء، تتلقى 409 business_brief_revision_conflict: اقرأ الإعدادات مجددًا قبل إعادة المحاولة.

تجربة مسار REST كامل

ينشئ هذا المثال المتقدم محتوى وقد يستهلك الحصة. استبدل المعرّفات والتواريخ المستقبلية ومفاتيح منع تكرار الطلب وبيانات الاعتماد التجريبية قبل تشغيله. تستخدم تواريخ التقويم المنطقة الزمنية IANA المحددة. افحص getCapabilities قبل اختيار وجهة CMS أو الفئة.
تعرض مجموعة مرجع API العامة جميع العمليات والحقول والاستجابات والأخطاء.

المتابعة وإعادة المحاولة

يتطلب كل تغيير Idempotency-Key فريدًا. استخدم المفتاح نفسه عند تكرار الأمر نفسه. اقرأ data.receipt.operation_id ثم استعلم عن getOperation حتى succeeded أو failed أو verification_pending. قبول الإيصال لا يعني اكتمال النشر. تعيد دفعة إنشاء المقالات 202 مع إيصال في الحالة succeeded مسبقًا؛ تابع كل مقال مذكور في selection.accepted_ids باستخدام getArticle. يُعاد التحقق من التفويض في كل استعلام، لذا يسري الإلغاء فورًا.

معالجة الأخطاء

لكل خطأ الشكل نفسه في REST وMCP: {"error": {"code", "message", "request_id", "retryable", "details"}}. اعتمد في منطقك على code لا على الرسالة. أعد المحاولة فقط عندما تكون قيمة retryable هي true، بعد Retry-After عند وجوده.
  • 401 invalid_credential: بيانات اعتماد غير صالحة أو منتهية أو ملغاة.
  • 403 missing_scope أو 403 onboarding_required؛ 402 subscription_required أو 402 insufficient_quota.
  • 404 not_found: المورد غير موجود أو غير متاح لبيانات الاعتماد هذه.
  • 409: تعارض مثل idempotency_conflict؛ 429 rate_limited: انتظر Retry-After.
  • 503 auth_state_unavailable: يُرفض الوصول حتى تتعافى حالة التفويض؛ أعد المحاولة لاحقًا.
يسرد مرجع واجهة API العامة رموز كل عملية. شارك code وrequest_id مع الدعم، ولا ترسل الرمز المميز أبدًا. لتوصيل مساعد، راجع دليل MCP.