التكاملات الخارجية عبر فريقي API

الواجهة متاحة على خطتَي المتطور والإنتاجي وخطة المؤسسات. أما الخطة المجانية والاحترافية فلا تشملان الوصول إلى API، وأي طلب منهما يُرفض بالرمز 403 ورسالة plan_upgrade_required، ولا فائدة من إعادة المحاولة.

السطح في مرحلة معاينة، ويُفعَّل لكل شركة على حدة. وما دام غير مفعّل لشركتك، يرجع كل مسار مصادَق عليه الرمز 404: السطح مخفي، لا ممنوع. يُفحص المفتاح أولاً، فالمفتاح الخاطئ يبقى 401، ثم يُفحص التفعيل، فلا يظهر الـ 404 إلا بعد تقديم مفتاح صالح.

لتفعيل الواجهة لشركتك، أو لطلب حدود أعلى، تواصل معنا وسنفعّلها على حسابك.

كل طلب يحمل مفتاح API في header Authorization بصيغة Bearer. ويُعرض المفتاح مرة واحدة عند إنشائه، ولا يُخزَّن منه إلا بصمته المشفّرة، فاحفظه حينها.

curl "https://app.fareeqy.com/api/v1/me" \
  -H "Authorization: Bearer $FAREEQY_API_KEY"

مفاتيح REST ورموز MCP بيانات اعتماد مختلفة، ولا يصادق أحدهما على واجهة الآخر.

• المفتاح ملك للشركة لا لمنشئه، ويستمر بعد مغادرته.

• عملية غير ممنوحة للمفتاح ← 403.

• يصل المفتاح إلى كل مشاريع شركته، ومنها الخاصة.

• سجل تابع لشركة أخرى ← 404.

• created_by اسم منشئ المفتاح، لا هوية تنفيذ الطلب.

• إدارة المفاتيح للمالك وللمصرّح له، وليست للمدير أو العضو افتراضياً.

كل مسار يعلن العملية الواحدة التي يطلبها، وهي نص ثابت بصيغة <المورد>:<القدرة> مثل projects:write. والمفتاح يُفحص مرتين قبل أن يمر الطلب.

• النطاق هو السقف: read أو write. ومفتاح write يحمل read معه. النطاق يقرر أي العمليات يجوز للمفتاح أن يحملها أصلاً.

• قائمة العمليات المسموحة هي البوابة الفعلية: العمليات التي يستطيع هذا المفتاح استدعاءها بالتحديد، ويُتحقق أنها ضمن ما يسمح به نطاقه. والقائمة الفارغة تعني لا شيء، فلا ينفتح مفتاح بالخطأ.

يجب أن يتحقق الشرطان معاً: أن تكون العملية في قائمة المفتاح، وأن يفي نطاقه بقدرتها. وإلا فالطلب مرفوض بالرمز 403، ويُسجَّل في سجل التدقيق بحالة denied.

الحذف اختياري بقرار صريح. عمليات destructive تحتاج نطاق write، لكنها مستثناة عمداً من المنح الافتراضي، فتُفعَّل كل عملية حذف يدوياً على المفتاح. اطّلع على جدول العمليات بالأسفل.

المشاريع، وقوائم المهام، والمهام، ومواضيع المجلس تُعنوَن بـ slug مقروء. والـ slug فريد داخل المورد الأب فقط، لذلك المسارات متداخلة بالكامل: يُحلّ slug القائمة داخل مشروعها، وslug المهمة داخل قائمتها. قد يتكرر slug القائمة نفسه في مشروعين، فلا تفترض أبداً أن الـ slug فريد عالمياً.

أما الملفات، والمجلدات، والأحداث، والتعليقات فتُعنوَن بمعرّفات رقمية. وهي عامة، لذلك تمرّ كل عملية بحث عنها عبر مشروعها (أو عبر ما تصل إليه أنت، في حالة الأحداث)، فمعرّف من شركة أخرى ينتهي إلى 404، لا إلى تسريب.

الـ slugs عربية لأن أسماء مشاريعك عربية. رمّزها ترميز URL قبل إرسالها: تطوير-الموقع تصبح %D8%AA%D8%B7%D9%88%D9%8A%D8%B1-.... أمثلة الطلبات هنا تعرض النص الأصلي ليبقى مقروءاً.

كل استجابة مغلّفة، فلا تتعامل مع مصفوفة عارية ولا مع حقل في الجذر.

• مورد واحد: { "data": { ... } }

• مجموعة: { "data": [ ... ], "meta": { total, limit, offset, count } }

• حذف: { "data": { "deleted": true, ... } }

• خطأ: { "error": { "code": "...", "message": "..." } }

المجموعات تستقبل limit (الافتراضي 50، والحد الأقصى 100، وما تجاوزه يُقصَر عليه) وoffset (الافتراضي 0). وmeta.total هو العدد الكلي بلا ترشيح، وmeta.count عدد السجلات في الصفحة المُرجَعة.

طبقتان مستقلتان، وترفضان بطريقتين مختلفتين.

الاندفاع. كل مفتاح محدود بـ 300 طلب في الدقيقة، ويسري حد مماثل لكل عنوان IP. وتجاوز أيهما يرجع 429.

الحصة اليومية. كل طلب يستهلك واحداً من رصيد الشركة اليومي. والرصيد للشركة لا للمفتاح، فإنشاء مفاتيح إضافية لا يرفعه، ويتجدد عند منتصف الليل بتوقيت شركتك.

الخطة بلا وصول ليست خطة محدودة السرعة: الرفض فيها 403 برمز plan_upgrade_required، ولا يصحبه Retry-After، لأن الانتظار لن ينفع أبداً. أما الخطة التي تملك وصولاً واستهلكت رصيد يومها فترجع 429 برمز rate_limit_exceeded ومعه Retry-After يشير إلى منتصف ليل شركتك القادم. الخلط بين الحالتين يدفع عميلاً منضبطاً إلى حلقة إعادة محاولة لا تنجح أبداً.

تُضاف الـ headers X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset إلى كل استجابة مخدومة، لا إلى الرفض وحده، حتى يبطئ عميلك قبل أن يصل إلى الصفر. وعلى خطة بلا سقف تقرأ الأوليان unlimited.