Tafsir API (spa5k) — مرجع المزوّد

العربية · English

• المعرّف: spa5k_tafsir · ملف المُحوّل: src/adapters/spa5k-tafsir.ts
• الصفحة الرئيسية: https://github.com/spa5k/tafsir_api
• المحتوى: تفسير · الاعتماد: لا شيء · يحتاج وسيطًا: لا

ما هذا المزوّد

مجموعةٌ مفتوحةٌ من كتب التفسير مُقدَّمةٌ ملفّاتٍ JSON ثابتة عبر شبكة توصيل (jsDelivr)، بلا مفاتيح. نجعلها مزوّدًا للتفسير في الإصدار الأول لأنّها تعمل دون أيّ اعتماد.

نقاط النهاية المستعملة

الرابط الأساس: https://cdn.jsdelivr.net/gh/spa5k/tafsir_api@main

• قائمة النسخ: GET /tafsir/editions.json — تُرجِع النسخ المتاحة ومعرّفاتها، مثل ar-tafsir-ibn-kathir وen-tafsir-ibn-kathir.
• تفسير آية: GET /tafsir/{edition}/{surah}_{ayah}.json

تنبيه: الصيغة الدقيقة لمسار الآية ومعرّفات النسخ يجب التحقّق منها من المستودع عند تنفيذ المُحوّل (التذكرة رقم 10)، فبنية المستودع قد تتغيّر. اجلب editions.json الحيّ أوّلًا، ثمّ ثبّت العيّنة.

بنية الاستجابة الخام

{
  "surah": 1,
  "ayah": 1,
  "text": "نصّ التفسير للآية..."
}

التحويل إلى البنية الموحّدة (والسبب)

التفسير → UnifiedTafsir:

الحقل الموحّد	المصدر الخام	ملاحظة
key	`${raw.surah}:${raw.ayah}`	مفتاح سورة:آية
text	raw.text	نصّ التفسير
edition	معرّف النسخة المطلوبة	مثل ar-tafsir-ibn-kathir
language	يُشتقّ من بادئة النسخة (ar/en)	لغة التفسير
source	"Tafsir API (spa5k)"	ثابت

يحدِّد المُحوّلُ النسخةَ الافتراضية (تفسيرٌ عربيٌّ مشهور)، ويمكن للمتصل تمرير edition عبر معاملات الطلب.

الاعتماد

لا يلزم؛ الملفّات ثابتةٌ عامّة عبر CDN.

حدود المعدّل والخصوصيات

توصيلٌ عبر jsDelivr بلا حدودٍ عمليّة تُذكر. التغطية بحسب النسخة؛ ليست كلُّ آيةٍ متوفّرةً في كلّ نسخة، فليتعامل المُحوّل مع الغياب بلطفٍ (عنصرٌ غير مُستوفًى لا خطأٌ عامّ).

إبقاء هذه الصفحة محدّثة

قبل التنفيذ أو التعديل، اجلب editions.json وملفَّ آيةٍ حقيقيًّا، ثبّت المسار الدقيق، وحدِّث العيّنة في test/fixtures/spa5k_tafsir/. فحصُ الانحراف عبر pnpm test:live.