المطورون

واجهة API العامة

اقرأ مواقعك وتقاريرك ومراتبك وكلماتك المفتاحية عبر واجهة API بسيطة تعتمد على مفتاح. ميزة Agency.

واجهة API العامة

توفر واجهة API العامة وصول قراءة فقط إلى البيانات التي يحتفظ بها RankMeFast بالفعل لحسابك: المواقع، وأحدث تقرير تدقيق، وسجل المراتب، والكلمات المفتاحية المتتبعة. إنها ميزة خطة Agency (انظر الخطط والحدود والأرصدة). لا تُطلق الواجهة أي عمل جديد لدى المزوّدين، بل تقرأ فقط ما أنتجته تدقيقاتك وفحوصات المراتب مسبقًا.

لا تشمل /api/v1 ميزة Content Intelligence: لا يمكن بدء تحليل أو تغيير توصية إلا داخل التطبيق بعد تسجيل الدخول. يستطيع MCP قراءة التحليلات المحفوظة، لكنه لا يستطيع بدء تحليل أو تغيير توصية.

المصادقة

أنشئ مفتاحًا من الحساب ← مفاتيح API (/profile?tab=api-keys). يُعرض المفتاح الكامل مرة واحدة فقط: انسخه فورًا؛ وبعدها لن يظهر سوى بادئته. يمكنك الاحتفاظ بما يصل إلى عشرة مفاتيح نشطة وإبطال أي منها في أي وقت. المفتاح المُبطل يتوقف عن العمل فورًا.

أرسل المفتاح كرمز bearer مع كل طلب:

Authorization: Bearer rmf_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

استبدل https://your-rankme-host في الأمثلة أدناه بأصل واجهة api لديك (قيمة SERVER_URL في تنصيبك).

لغة الاستجابة وعقد البيانات

اختر لغة الاستجابة عبر x-lang ثم Accept-Language، وإلا تستخدم الواجهة en. تتحول القيم الإقليمية مثل fr-CA إلى fr. يتجاهل /api/v1 ملفات تعريف الارتباط للمتصفح ولغة الحساب وتفضيلات مساحة العمل. تذكر كل استجابة اللغة المستخدمة في Content-Language وتضيف x-lang, Accept-Language إلى Vary مع الإبقاء على القيم الموجودة.

لا يُترجم إلا النص الذي يكتبه RankMeFast (نصوص التقارير والنتائج والإجراءات ورسائل الأخطاء الآمنة). لا تتغير أسماء خصائص JSON أو حالات HTTP أو رموز الأخطاء الثابتة أو قيم التعداد والحالة أو المعرّفات أو النطاقات أو عناوين URL أو الكلمات المفتاحية أو الطوابع الزمنية أو القياسات أو الملاحظات أو المؤشرات أو نص المستخدم والمزود المخزن. ولا تغيّر اللغة الفرز أو تنسيق الأرقام والتواريخ أبدًا.

يبقى ملف CSV متطابقًا بايتًا ببايت في كل اللغات: BOM بترميز UTF-8، وأسماء الرؤوس وترتيبها، وترتيب الصفوف، واقتباس RFC-4180، والقيم، ونهايات الأسطر، واسم الملف، ورؤوس التقسيم، وسلوك المؤشر. يذكر Content-Language اللغة المختارة، لكنه لا يترجم أي شيء في CSV ولا يعيد تسميته.

نقاط النهاية

قائمة مواقعك

curl -H "Authorization: Bearer rmf_..." \
  https://your-rankme-host/api/v1/sites

تعيد { "sites": [{ "id", "domain", "url", "createdAt" }] }.

أحدث تقرير تدقيق لموقع

curl -H "Authorization: Bearer rmf_..." \
  https://your-rankme-host/api/v1/sites/<siteId>/report/latest

تعيد أحدث تدقيق ناجح بالشكل { "runId", "report" } مع نفس النتائج والفئات والنصوص المترجمة التي تعرضها لوحة التحكم. تجيب بـ 404 إذا لم يكن للموقع تدقيق مكتمل بعد.

سجل المراتب لموقع

curl -H "Authorization: Bearer rmf_..." \
  "https://your-rankme-host/api/v1/sites/<siteId>/rank-history?from=2026-06-01&to=2026-07-01"

تعيد { "keywords": [{ "id", "phrase", "series": [...] }] }. تحمل كل نقطة في السلسلة المرتبة وعنوان URL الذي تصدّر وإشارات Google AI Overview (aiOverviewPresent، aiCited، aiCitedUrl). from وto تاريخان بصيغة ISO اختياريان.

كل الكلمات المفتاحية المتتبعة

curl -H "Authorization: Bearer rmf_..." \
  https://your-rankme-host/api/v1/keywords

تعيد كل كلمة مفتاحية متتبعة عبر جميع مواقعك مع أحدث مرتبة والفرق وحقول AI Overview.

تصدير CSV والصفوف المخزنة

عند تفعيل PUBLIC_EXPORTS_ENABLED اطلب CSV من أي مسار قائمة عبر ?format=csv أو Accept: text/csv. تستخدم الملفات أعمدة ثابتة وBOM بترميز UTF-8 واقتباس RFC-4180 ونصًا آمنًا من الصيغ، بينما تبقى استجابات JSON الأصلية كما هي. يقبل سجل الترتيب engine=google|bing|youtube|amazon، ويعرض كل المحركات افتراضيًا في عمود engine.

يحتفظ CSV لسجل الترتيب والكلمات المفتاحية بالمخرجات القديمة غير المقسّمة ما لم تضف limit أو cursor معتمًا. تقبل صفحة سجل الترتيب من 1 إلى 25 مجموعة كلمات مفتاحية (بحد 730 نقطة لكل مجموعة)، وتقبل صفحة الكلمات المفتاحية من 1 إلى 1,000 صف. أرسل قيمة X-Next-Cursor في الطلب التالي وتوقّف عند غياب هذا الرأس. تتجاهل JSON معاملات تقسيم CSV هذه وتحافظ على عقد الاستجابة الأصلي.

توجد قراءتان إضافيتان للبيانات المخزنة: GET /api/v1/serp-features?siteId=<siteId> وGET /api/v1/backlink-rows?siteId=<siteId>. تقبلان limit من 1 إلى 1,000 ومؤشر cursor معتمًا، وتعيدان صفوف الحساب فقط مع الوسم sourceKind=provider_observation (source_kind في CSV). عند إيقاف العلم تجيب المسارات الجديدة وCSV بـ503 وتظل مسارات JSON الأصلية متاحة. راجع دليل Looker Studio لإعداد الموصل والحقول.

حدود المعدل

افتراضيًا يمكن لكل مفتاح إجراء 120 طلبًا في الدقيقة. بعد ذلك تجيب واجهة API بـ 429 حتى تتم إعادة ضبط النافذة.

الأخطاء

تستخدم الأخطاء الشكل { "error": { "message": "...", "details": ... } }. تتبع الرسالة المقروءة x-lang ثم Accept-Language ثم en، ولا تتغير الحالة والحقول والرموز الثابتة والتفاصيل بتغيّر اللغة:

401: المفتاح مفقود أو تالف أو مُبطل أو غير معروف.
402: خطتك لا تتضمن واجهة API.
404: الموقع أو التقرير غير موجود في حسابك.
429: تم تجاوز حد المعدل (المحتوى: { "error": "..." }).

التوافق

يوفّر هذا الإصدار ستة مسارات للقراءة فقط:

GET /api/v1/sites
GET /api/v1/sites/:siteId/report/latest
GET /api/v1/sites/:siteId/rank-history
GET /api/v1/keywords
GET /api/v1/serp-features
GET /api/v1/backlink-rows

لا توجد مسارات تحت /api/v1 لرادار العلامة التجارية أو ذكاء المراجعات أو ذكاء الروابط أو تحليلات الزيارات أو اتجاهات الكلمات المفتاحية. هذه الميزات متاحة في لوحة التحكم بعد تسجيل الدخول. تحتفظ حقول الاستجابة الحالية بمعناها، ويجب على العملاء تجاهل الحقول الجديدة التي لا يعرفونها.

العودة إلى فهرس الوثائق