عنوان الإنتاج وأول طلب
سجّل الدخول إلى التطبيق علىhttps://app.sorank.com. تُدار المفاتيح على https://app.sorank.com/settings/api، والعنوان الأساسي لطلبات REST هو https://app.sorank.com/api/public/v1. لا تحتاج إلى إنشاء خادم API.
- افتح الإعدادات ← الوصول إلى API وأنشئ مفتاحًا باسم وموقع واحد على الأقل وصلاحية عرض المواقع (
profiles:read) وتاريخ انتهاء. أضف عرض الحصص (quotas:read) للطلب الثاني. - انسخ المفتاح الكامل فورًا؛ يظهر مرة واحدة فقط. البادئة المعروضة لاحقًا لا تكفي للمصادقة.
- اختر مثالًا. في cURL أدخل المفتاح عند المطالبة به. في JavaScript أو Go اضبط
SORANK_API_KEYفي بيئة عملية الخادم. تتضمن علامة تبويب HTML خادم Node.js محليًا: شغّله والمفتاح في بيئته ثم افتحhttp://127.0.0.1:3100. لا تضع المفتاح داخل HTML أو JavaScript في المتصفح. أضف مصادقة تطبيقك قبل استخدام هذا النمط خارج العرض المحلي.
- cURL
- HTML
- JavaScript
- Go
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 أو الفئة.
المتابعة وإعادة المحاولة
يتطلب كل تغيير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: يُرفض الوصول حتى تتعافى حالة التفويض؛ أعد المحاولة لاحقًا.
code وrequest_id مع الدعم، ولا ترسل الرمز المميز أبدًا.
لتوصيل مساعد، راجع دليل MCP.
