REST API

توثيق الواجهة البرمجية

Documentation API

API REST · Coran · Hadiths · Tafsir · Duas & Dhikr

Authentification

Chaque requête doit inclure votre clé API via le header X-API-Key ou le paramètre ?api_key=.

# Via header (recommandé)
curl -H "X-API-Key: hc_votre_cle" https://www.halal-club.com/api/v1/quran

# Via query param
curl "https://www.halal-club.com/api/v1/quran?api_key=hc_votre_cle"

Obtenir une clé gratuite Gérer mes clés

Coran

GET/api/v1/quran

Liste les 114 sourates avec leurs métadonnées.

Exemple

curl -H "X-API-Key: hc_xxx" https://www.halal-club.com/api/v1/quran

Réponse

{ "ok": true, "data": [{ "number": 1, "name_arabic": "الفاتحة", "transliteration": "Al-Fatihah", "total_verses": 7, "type": "meccan" }, ...], "meta": { "total": 114 } }

GET/api/v1/quran/{surah}

Récupère une sourate complète avec tous ses versets.

Paramètres

langar | fr | en | all — langue des versets (défaut : all)

Exemple

curl -H "X-API-Key: hc_xxx" "https://www.halal-club.com/api/v1/quran/1?lang=fr"

Réponse

{ "ok": true, "data": { "surah": { ... }, "verses": [{ "verse_number": 1, "text_arabic": "...", "text_french": "..." }] } }

GET/api/v1/quran/{surah}/{ayah}

Récupère un verset unique.

Exemple

curl -H "X-API-Key: hc_xxx" https://www.halal-club.com/api/v1/quran/2/255

GET/api/v1/quran/random

Renvoie un verset aléatoire du Coran.

Paramètres

surahRestreindre à une sourate donnée (optionnel)

langar | fr | en | all (défaut : all)

Exemple

curl -H "X-API-Key: hc_xxx" "https://www.halal-club.com/api/v1/quran/random?lang=en"

Hadiths

GET/api/v1/hadiths

Liste toutes les collections de hadiths disponibles.

Exemple

curl -H "X-API-Key: hc_xxx" https://www.halal-club.com/api/v1/hadiths

GET/api/v1/hadiths/{book}

Hadiths d'un livre, paginés.

Paramètres

pageNuméro de page (défaut : 1)

limitRésultats par page (défaut : 50, max : 100)

chapterFiltrer par chapitre (optionnel)

Exemple

curl -H "X-API-Key: hc_xxx" "https://www.halal-club.com/api/v1/hadiths/bukhari?page=1&limit=20"

Réponse

{ "ok": true, "data": [...], "meta": { "book_key": "bukhari", "total": 7563, "page": 1, "total_pages": 152 } }

GET/api/v1/hadiths/{book}/{id}

Hadith unique par son numéro dans le livre, avec les infos du chapitre.

Exemple

curl -H "X-API-Key: hc_xxx" https://www.halal-club.com/api/v1/hadiths/bukhari/1

GET/api/v1/hadiths/random

Renvoie un hadith aléatoire avec les métadonnées du livre.

Paramètres

bookRestreindre à un livre donné — ex : bukhari (optionnel)

Exemple

curl -H "X-API-Key: hc_xxx" "https://www.halal-club.com/api/v1/hadiths/random?book=muslim"

Tafsir

GET/api/v1/tafsir

Liste toutes les éditions de Tafsir disponibles (9 éditions).

Exemple

curl -H "X-API-Key: hc_xxx" https://www.halal-club.com/api/v1/tafsir

GET/api/v1/tafsir/{edition}/{surah}/{ayah}

Récupère le tafsir d'un verset précis selon une édition donnée.

Exemple

curl -H "X-API-Key: hc_xxx" https://www.halal-club.com/api/v1/tafsir/en-tafsir-ibn-kathir/1/1

Réponse

{ "ok": true, "data": { "edition": { ... }, "surah_number": 1, "ayah_number": 1, "text": "..." } }

Duas & Dhikr

GET/api/v1/duas

Liste les 5 catégories de duas et dhikr avec leur nombre d'invocations.

Exemple

curl -H "X-API-Key: hc_xxx" https://www.halal-club.com/api/v1/duas

Réponse

{ "ok": true, "data": [{ "slug": "morning-dhikr", "name_en": "Morning Dhikr", "name_ar": "أذكار الصباح", "total": 19 }, ...], "meta": { "total": 5 } }

GET/api/v1/duas/{category}

Renvoie toutes les duas d'une catégorie, paginées.

Paramètres

pageNuméro de page (défaut : 1)

limitRésultats par page (défaut : 20, max : 100)

Exemple

curl -H "X-API-Key: hc_xxx" https://www.halal-club.com/api/v1/duas/morning-dhikr

GET/api/v1/duas/{category}/{id}

Récupère une dua précise par son numéro de position dans la catégorie.

Exemple

curl -H "X-API-Key: hc_xxx" https://www.halal-club.com/api/v1/duas/morning-dhikr/1

GET/api/v1/duas/random

Renvoie une dua aléatoire avec les métadonnées de sa catégorie.

Paramètres

categoryRestreindre à une catégorie — ex : morning-dhikr (optionnel)

Exemple

curl -H "X-API-Key: hc_xxx" "https://www.halal-club.com/api/v1/duas/random?category=evening-dhikr"

Recherche

GET/api/v1/search

Recherche textuelle dans les versets, les hadiths et les duas simultanément.

Paramètres

qTerme de recherche (obligatoire, min 3 caractères)

typeayah | hadith | dua | all — type de contenu (défaut : all)

langfr | en | ar — langue de recherche (défaut : en)

limitRésultats max par type (défaut : 10, max : 50)

Exemple

curl -H "X-API-Key: hc_xxx" "https://www.halal-club.com/api/v1/search?q=mercy&type=all&lang=en&limit=5"

Réponse

{ "ok": true, "data": { "ayahs": [...], "hadiths": [...], "duas": [...] }, "meta": { "query": "mercy", "counts": { "ayahs": 5, "hadiths": 5, "duas": 2 } } }

Références

Livres de Hadiths

bukharimuslimabudawudtirmidhinasaiibnmajahmalikahmeddariminawawi40qudsi40riyad_assalihinbulugh_almaramaladab_almufradmishkat_almasabihshamail_muhammadiyahshahwaliullah40

Éditions Tafsir

ar-tafsir-ibn-kathirar-tafseer-al-qurtubiar-tafsir-al-tabariar-al-wasitar-al-muyassarar-asbab-al-nuzulen-tafsir-ibn-kathiren-al-jalalaynen-tafsir-ibn-abbas

Catégories Duas

morning-dhikrevening-dhikrdaily-duadhikr-after-salahselected-dua

Format des réponses

response.json

// ✅ Succès
{
  "ok": true,
  "data": { ... },
  "meta": { "total": 97, "page": 1, "total_pages": 5 }
}

// ❌ Clé manquante (401)
{ "error": "API key required." }

// ❌ Clé invalide (403)
{ "error": "Invalid or inactive API key." }

// ❌ Ressource introuvable (404)
{ "error": "Category not found." }