Quran Foundation — مرجع المزوّد

العربية · English

• المعرّف: quran_foundation · ملف المُحوّل: src/adapters/quran-foundation.ts
• الصفحة الرئيسية / التوثيق: https://quran.com · https://api-docs.quran.foundation
• المحتوى: نصّ · الاعتماد: OAuth2 (بيانات عميل) · يحتاج وسيطًا: لا

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

الواجهة الرسمية لمؤسسة القرآن (Quran.com)، الإصدار الرابع (v4). تتميّز بتخطيطات المصحف الرسمية ونصٍّ عثمانيٍّ موثوق. نجعلها مزوّدًا للنصّ.

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

الرابط الأساس: https://api.quran.com/api/v4

• النصّ (آية): GET /quran/verses/uthmani?verse_key={surah}:{ayah}

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

{
  "verses": [
    {
      "id": 1,
      "verse_key": "1:1",
      "text_uthmani": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
      "juz_number": 1,
      "page_number": 1
    }
  ]
}

الاستجابة مصفوفةٌ باسم verses؛ يأخذ المُحوّل عنصرها الأول.

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

النصّ → UnifiedVerse:

الحقل الموحّد	المصدر الخام	ملاحظة
key	verses[0].verse_key	جاهزٌ بصيغة سورة:آية
id	verses[0].id	معرّف المزوّد للآية
text	verses[0].text_uthmani	النصّ العثماني
source	"Quran Foundation"	ثابت
meta.juz / meta.page	juz_number / page_number	بيانات موضعية

نقرأ العنصر الأول من verses لأنّ نقطة النهاية تعيد الآية المطلوبة داخل مصفوفة.

الاعتماد

كانت نقاطُ نهاية api.quran.com/api/v4 مفتوحةً تاريخيًا، غير أنّ البوّابة الرسمية لمؤسسة القرآن باتت تُصدر بيانات عميل OAuth2 (clientId وsecret). مرِّرها هكذا:

createQuranClient({
  credentials: { quran_foundation: { clientId: '...', secret: '...' } },
})

عند غياب الاعتماد يُتخطَّى المُحوّل في الاختيار التلقائيّ، ولا يُطلق خطأً إلا إذا طُلب بالاسم صراحةً. تُوثَّق المفاتيح في .env.example لاستعمال الاختبار الحيّ.

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

راجِع سياسة المؤسسة الحالية عبر بوّابة المطوّرين. صيغةُ verse_key هي سورة:آية.

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

قبل تعديل المُحوّل، راجِع توثيق api-docs.quran.foundation الحيّ وحدِّث العيّنة في test/fixtures/quran_foundation/. فحصُ الانحراف عبر pnpm test:live.