ابدأ من هنا

العنوان الأساسي والصيغة

تبدأ جميع المسارات (endpoints) بـ https://islamenc.com/api، وتُرجع البيانات بصيغة JSON وترميز UTF-8. لا تحتاج إلى مفتاح وصول أو توقيع للطلب؛ يكفي إرسال طلب GET. يُرجع النص العربي كما ورد في المصدر. النص القرآني يأتي بالرسم العثماني، ومعه الرسم الإملائي في المسارات التي توفره.

curl -s "https://islamenc.com/api/languages" | head -c 300

[{"isoCode":"aa","arabicName":"عفري","englishName":"Afar","nativeName":"Qafár af","direction":"ltr"}, ...

اللغات

كل لغة لها رمز ISO (en، fr، bn، prs…). يعرض المسار GET /languages اللغات الـ147 المسجلة في المنصة مع أسمائها واتجاه كتابتها. قد لا يتوفر المحتوى بجميع اللغات. تحقّق من اللغات المتاحة أولًا: لغات الكتاب من /languages، ولغات بطاقات الموسوعة من /card-languages، وترجمات القرآن من /translation-keys.

أغلب المسارات تقبل lang:

في القوائم يضيف العنوان أو الوصف المترجم إن وُجد (/books?lang=fr)، أو يقصر العدّ على تلك اللغة (/enc?lang=en).
في المحتوى يختار الترجمة (/quran/surahs/2?lang=fr، /enc/cards/7913?lang=en). والأصل العربي يأتي معها دائمًا.

العربية هي لغة الأصل لكل المحتوى. إذا أرسلت lang=ar أو لم ترسل lang حصلت على المحتوى كاملًا.

المعرّفات

نوع المحتوى	المعرّف	مثال
سورة	`surah_no` من 1 إلى 114	`2`
آية	`surah_no` و`aya_no`	السورة `2`، الآية `255`
كتاب	`project_id`	`36`
إصدار كتاب	`version_name`	`2.0`
موسوعة	`external_id`	`101` موسوعة الأحاديث
بطاقة	`external_id`	`7913`
تصنيف	`"<table>:<item>"`	`11:2` هو “الحديث وعلومه” في التصنيف الشرعي
قيمة خاصية	`"<table>:<item>"` تحت معرّف خاصية `t<table>`	`t40` = `40:1` بطاقة مختصرة

كل هذه المعرّفات ثابتة: تحتفظ البطاقة بـexternal_id عبر إصداراتها، ويحتفظ الكتاب بـproject_id عبر طبعاته.

تقسيم النتائج إلى صفحات

أسلوبان بحسب المسار:

page وlimit في قائمة البطاقات: GET /enc/101/cards?page=2&limit=20 يُرجع { "cards": [...], "total": 839 }. الحد الأقصى لـlimit هو 100. بدون page تُرجع الاستجابة كل البطاقات في استجابة واحدة. الموقع نفسه يستخدم هذا الأسلوب، وحجم الاستجابة لموسوعة الأحاديث بضعة ميجابايت.
offset وlimit في مسارات البحث: GET /hybrid-search?q=...&offset=10&limit=10. الحد الأقصى لـlimit هو 50، ولمجموع offset + limit هو 1000. ويخبرك hasMore (مع format=hits) إن كانت هناك صفحة أخرى.

لا تُقسّم نتائج مسارات القرآن والفهرس واللغات إلى صفحات: تُرجع الاستجابة السورة أو قائمة الكتب أو قائمة اللغات كاملة.

الأخطاء

تستخدم الواجهة رموز HTTP المعتادة مع استجابة JSON قصير يشرح الخطأ:

{ "statusCode": 404, "message": "Book 999 not found" }

الرمز	السبب
`400`	معامل ناقص أو بصيغة خاطئة (`q` غائب، `type` غير معروف، حد خارج النطاق). يوضّح `message` أيّها.
`404`	السورة أو الكتاب أو الإصدار أو البطاقة أو اللغة غير موجود، أو الكتاب أُزيل من النشر.
`429`	أكثر من 10 طلبات في الثانية من عنوان واحد. قلّل معدل الطلبات وأعد المحاولة بعد قليل.
`500` / `502` / `503`	خطأ في الخادم، أو أن الواجهة قيد إعادة التشغيل. أعد المحاولة بعد قليل، وزد فترة الانتظار في كل محاولة.

ملاحظة: طلب كتاب غير موجود من GET /books/{projectId} يُرجع حاليًا الرمز 200 واستجابة فارغة بدل 404. تحقّق من الاستجابة الفارغة في تطبيقك.

حد الطلبات والتخزين المؤقت

الحد 10 طلبات في الثانية لكل عنوان IP، مع السماح بدفعات قصيرة تصل إلى 40 طلبًا. يناسب هذا الحد تحميل سورة وعدة بطاقات، أو قراءة الفهرس كاملًا بمعدل طلبات منتظم. إن احتجت حدًا أعلى بشكل دائم، راسلنا ووضّح احتياجات تطبيقك.

تحمل كل استجابة قابلة للتخزين المؤقت الترويسة Cache-Control: public, max-age=600, stale-while-revalidate=3600. المحتوى يُحدَّث من المصدر بضع مرات في الأسبوع، ويمكن تخزين الاستجابات مؤقتًا وفقًا للمدد المحددة في الترويسة. تخزّن الواجهة أكبر استجابتين (جميع بطاقات الموسوعة وفهرس الكتب) في ذاكرتها المؤقتة، مما يتيح إرجاعهما في أجزاء من الثانية بعد الطلب الأول.

الاستخدام من المتصفح مباشرة

CORS مفعّل، فيمكنك استدعاء الواجهة من JavaScript في المتصفح مباشرة:

const q = encodeURIComponent("فضل الصدقة");
const res = await fetch(`https://islamenc.com/api/hybrid-search?q=${q}&limit=5&lang=en`);
const { results } = await res.json();

استخدم encodeURIComponent لترميز النصوص العربية (نص البحث وأسماء الحقول مثل fields=متن الحديث) قبل وضعها في الرابط.

حدود الواجهة

الواجهة للقراءة فقط: لا يوجد مسار ينشئ محتوى أو يعدّله أو يحذفه. المحتوى يأتي من منصتي ICADB وQuranEnc ويُحدَّث بضع مرات في الأسبوع.
لا تدعم الواجهة حسابات المستخدمين أو المفضّلة أو حفظ حالة المستخدم.
لا توفر الواجهة ملفات صوتية؛ يقتصر محتوى القرآن على النص والترجمات.