Documentation API

API REST publique pour accéder au Coran, aux Hadiths et aux Tafsirs. Nécessite une clé API gratuite.

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: ih_votre_cle_api" https://www.halal-club.com/api/v1/quran

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

Obtenir une clé API gratuite

Utiliser avec Postman

1
Ouvrir Postman et créer une nouvelle requête
Sélectionnez la méthode GET et entrez l'URL :
```
https://www.halal-club.com/api/v1/quran
```
2
Ajouter le header d'authentification
Dans l'onglet Headers, ajoutez :
```
Key:   X-API-Key
Value: ih_votre_cle_api
```
3
Envoyer la requête
Cliquez sur Send. Vous recevrez un JSON avec "ok": true et les données dans "data".

Astuce : Pour configurer la clé une seule fois dans Postman, allez dans Collections → Authorization → API Key, renseignez X-API-Key comme header key, et toutes vos requêtes de la collection hériteront de l'auth.

Endpoints

GET/api/v1/quran

Liste toutes les sourates (metadata)

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

GET/api/v1/quran/{surah}

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

Paramètres : lang: ar | fr | en | all (défaut: all)

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

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

Récupère un verset unique

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

GET/api/v1/hadiths

Liste toutes les collections de hadiths

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

GET/api/v1/hadiths/{book}

Hadiths d'un livre, paginés

Paramètres : page (défaut: 1) · limit (défaut: 50, max: 100) · chapter

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

GET/api/v1/tafsir

Liste toutes les éditions de Tafsir disponibles

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

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

Tafsir d'un verset spécifique

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

Clés des livres de Hadiths

bukharimuslimabudawudtirmidhinasaiibnmajahmalikahmeddariminawawi40qudsi40riyad_assalihinbulugh_almaramaladab_almufradmishkat_almasabihshamail_muhammadiyahshahwaliullah40

Slugs des éditions Tafsir

ar-tafsir-ibn-kathirar-tafseer-al-qurtubiar-tafsir-al-tabariar-tafsir-al-wasitar-tafsir-muyassaren-tafsir-ibn-kathiren-al-jalalaynen-tafsir-ibn-abbasen-asbab-al-nuzul-by-al-wahidi

Format des réponses

// Succès
{
  "ok": true,
  "data": { ... },
  "meta": { "total": 114, "page": 1, "total_pages": 6 }
}

// Erreur — clé manquante (401)
{ "error": "API key required. Pass it via X-API-Key header or ?api_key= query param." }

// Erreur — clé invalide (403)
{ "error": "Invalid or inactive API key." }