Priceflow/docs/API_CATALOGUES.md

API Documentation - Module Catalogues Bonial

Vue d'ensemble

Le module Catalogues permet de consulter les catalogues promotionnels des enseignes discount scrapers depuis Bonial.fr.

Base URL: /api/catalogues

Endpoints Publics

1. Liste des Enseignes

GET /api/catalogues/enseignes

Retourne la liste de toutes les enseignes actives avec le nombre de catalogues en cours.

Réponse : 200 OK

[
  {
    "id": 1,
    "nom": "Gifi",
    "slug_bonial": "Gifi",
    "logo_url": null,
    "couleur": "#E30613",
    "site_url": "https://www.gifi.fr",
    "description": "Décoration, maison, bazar",
    "is_active": true,
    "ordre_affichage": 1,
    "catalogues_actifs_count": 3
  }
]

---

2. Liste des Catalogues (Paginée)

GET /api/catalogues

Retourne la liste paginée des catalogues avec filtres.

Paramètres Query :

• page (int, default=1): Numéro de page
• limit (int, default=20, max=100): Nombre d'éléments par page
• enseigne_ids (string, optional): IDs d'enseignes séparés par virgule (ex: 1,2,3)
• statut (string, optional): Filtre par statut (actif, termine, tous)
• date_debut_min (datetime, optional): Date de début minimum
• date_fin_max (datetime, optional): Date de fin maximum
• recherche (string, optional): Recherche dans les titres
• sort (string, default=date_debut): Tri (date_debut, date_fin, enseigne)
• order (string, default=desc): Ordre (asc, desc)

Réponse : 200 OK

{
  "data": [
    {
      "id": 42,
      "enseigne": {
        "id": 1,
        "nom": "Gifi",
        "couleur": "#E30613",
        ...
      },
      "titre": "Catalogue Gifi Noël 2024",
      "date_debut": "2024-11-25T00:00:00",
      "date_fin": "2024-12-24T23:59:59",
      "image_couverture_url": "https://content-media.bonial.biz/...",
      "statut": "actif",
      "nombre_pages": 24,
      "created_at": "2024-11-29T06:00:00"
    }
  ],
  "pagination": {
    "total": 156,
    "page": 1,
    "limit": 20,
    "pages_total": 8
  },
  "metadata": {
    "derniere_mise_a_jour": "2024-11-29T06:15:32"
  }
}

---

3. Détail d'un Catalogue

GET /api/catalogues/{catalogue_id}

Retourne les informations détaillées d'un catalogue.

Paramètres Path :

• catalogue_id (int): ID du catalogue

Réponse : 200 OK

{
  "id": 42,
  "enseigne": {
    "id": 1,
    "nom": "Gifi",
    ...
  },
  "titre": "Catalogue Gifi Noël 2024",
  "description": null,
  "date_debut": "2024-11-25T00:00:00",
  "date_fin": "2024-12-24T23:59:59",
  "image_couverture_url": "https://content-media.bonial.biz/...",
  "catalogue_url": "https://www.bonial.fr/...",
  "statut": "actif",
  "nombre_pages": 24,
  "metadonnees": null,
  "created_at": "2024-11-29T06:00:00",
  "updated_at": "2024-11-29T06:00:00"
}

Erreurs :

• 404 Not Found: Catalogue introuvable

---

4. Pages d'un Catalogue

GET /api/catalogues/{catalogue_id}/pages

Retourne toutes les pages d'un catalogue, ordonnées par numéro.

Paramètres Path :

• catalogue_id (int): ID du catalogue

Réponse : 200 OK

[
  {
    "id": 128,
    "numero_page": 1,
    "image_url": "https://content-media.bonial.biz/.../page_1.jpg",
    "image_thumbnail_url": null,
    "largeur": 1200,
    "hauteur": 1600
  },
  {
    "id": 129,
    "numero_page": 2,
    "image_url": "https://content-media.bonial.biz/.../page_2.jpg",
    "image_thumbnail_url": null,
    "largeur": 1200,
    "hauteur": 1600
  }
]

Erreurs :

• 404 Not Found: Catalogue introuvable

---

Endpoints Admin (Authentification requise)

5. Déclencher Scraping Manuel

POST /api/catalogues/admin/scraping/trigger

Déclenche un scraping manuel des catalogues Bonial.

Authentification : Requise (JWT token + rôle admin)

Paramètres Query :

• enseigne_id (int, optional): ID de l'enseigne à scraper. Si omis, scrape toutes les enseignes actives.

Réponse : 200 OK

{
  "success": true,
  "message": "Scraping complete for Gifi",
  "catalogues_trouves": 4,
  "catalogues_nouveaux": 2
}

Ou pour toutes les enseignes :

{
  "success": true,
  "message":" Scraping complete for all enseignes",
  "enseignes_processed": 9,
  "catalogues_trouves": 38,
  "catalogues_nouveaux": 12
}

Erreurs :

• 403 Forbidden: Accès admin requis
• 404 Not Found: Enseigne introuvable

---

6. Historique des Scraping

GET /api/catalogues/admin/scraping/logs

Retourne l'historique des exécutions de scraping.

Authentification : Requise (JWT token + rôle admin)

Paramètres Query :

• limit (int, default=50, max=200): Nombre de logs à retourner
• enseigne_id (int, optional): Filtre par enseigne
• statut (string, optional): Filtre par statut (success, error, partial)

Réponse : 200 OK

[
  {
    "id": 15,
    "date_execution": "2024-11-29T06:00:15",
    "enseigne_id": 1,
    "enseigne_nom": "Gifi",
    "statut": "success",
    "catalogues_trouves": 4,
    "catalogues_nouveaux": 2,
    "catalogues_mis_a_jour": 0,
    "duree_secondes": 45.2,
    "message_erreur": null
  }
]

---

7. Statistiques de Scraping

GET /api/catalogues/admin/stats

Retourne les statistiques globales du module catalogues.

Authentification : Requise (JWT token + rôle admin)

Réponse : 200 OK

{
  "total_catalogues": 156,
  "catalogues_par_enseigne": {
    "Gifi": 18,
    "Action": 22,
    "Centrakor": 15,
    "La Foir'Fouille": 12,
    "Stokomani": 19,
    "B&M": 14,
    "L'Incroyable": 11,
    "Bazarland": 8,
    "Noz": 17
  },
  "derniere_mise_a_jour": "2024-11-29T06:15:32",
  "prochaine_execution": "Aujourd'hui à 18:00"
}

---

Erreurs Communes

400 Bad Request

{
  "detail": "Invalid enseigne_ids format"
}

403 Forbidden

{
  "detail": "Admin access required"
}

404 Not Found

{
  "detail": "Catalogue not found"
}

500 Internal Server Error

{
  "detail": "Internal server error"
}

---

Scheduler Automatique

Le scraping est exécuté automatiquement 2 fois par jour :

• 6h00 : Scraping matinal
• 18h00 : Scraping du soir

Les catalogues sont automatiquement marqués comme termine lorsque leur date_fin est dépassée.

---

Notes d'Implémentation

Détection de Doublons

Le système utilise un hash SHA-256 basé sur :

• enseigne_id
• titre
• date_debut

Cela évite de créer des doublons même si le catalogue est re-scrapé.

Performance

• Pagination obligatoire (max 100 items/page)
• Index DB sur enseigne_id, date_debut, date_fin, statut
• Scraping asynchrone (n'impacte pas les performances API)

Formats de Date

Toutes les dates sont en ISO 8601 avec timezone UTC :

2024-11-29T06:15:32+00:00