Moteur d'importation

Ce document décrit comment le plugin ADP Car Market Hub importe les annonces de véhicules depuis l'API AutoScout24 vers WordPress. Il couvre les responsabilités des classes d'importation, le flux par annonce, la détection des modifications, la suppression par synchronisation complète et le hook public qui se déclenche après l'importation d'un véhicule.

Quand utiliser ce document

Lisez ce document si vous devez :

• Comprendre ce qui se passe lors d'une exécution d'importation.
• Diagnostiquer pourquoi un véhicule a été inséré, mis à jour, ignoré ou supprimé.
• Créer une intégration personnalisée qui réagit aux importations via l'action as24ci_vehicle_imported.
• Planifier la capacité ou la configuration requise pour l'hébergement de grands catalogues.

Pour les détails de planification et de cron, voir Cron et traitement en arrière-plan. Pour la gestion des images, voir Image Importer And Queue.

Aperçu

Le moteur d'importation se compose de plusieurs classes qui fonctionnent ensemble :

• AS24CI\Client — émet des requêtes HTTP authentifiées vers l'API AutoScout24, gère les jetons OAuth (y compris le cache transitoire as24ci_access_token) et expose des assistants pour les pages de prévisualisation et les équipements par annonce.
• AS24CI\Importer — coordonne l'importation par annonce. Décide s'il faut insérer, mettre à jour ou ignorer, et écrit l'article du véhicule, les postmeta et les références d'images. Gère la détection des modifications.
• AS24CI\Mapper — mappe le payload brut de AutoScout24 vers les champs stockés dans la table as24_vehicles via AS24CI\Vehicle_Repository. Maintient des clés postmeta rétrocompatibles.
• AS24CI\Vehicle_Repository — persiste les données de champs de véhicules dans la table dédiée {$wpdb->prefix}as24_vehicles.
• AS24CI\Image_Importer — télécharge les images, les convertit éventuellement en WebP, et les associe à l'article du véhicule. Voir Image Importer And Queue.
• AS24CI\Scheduler — enveloppe Importer::import_all_for_seller() dans un exécuteur sécurisé contre les verrouillages et les tentatives, utilisé par WP-Cron, le point de terminaison REST cron et le bouton manuel « Exécuter maintenant ».

La même instance Importer est réutilisée par l'assistant de lot manuel (Batch-Wizard), l'exécuteur cron et le point de terminaison REST cron.

Configuration requise ou prérequis

Avant de lancer une importation, vous avez besoin de :

• Identifiants API AutoScout24 valides configurés dans le plugin (as24ci_base_url, as24ci_token_url, as24ci_client_id, as24ci_client_secret, as24ci_token_audience).
• Un ou plusieurs Seller IDs dans as24ci_seller_ids (séparés par des virgules).
• Un utilisateur WordPress désigné comme auteur par défaut de l'article (as24ci_default_post_author) ; les importations se rabattent sur l'utilisateur actuel lorsqu'aucun auteur par défaut n'est défini.
• Un accès HTTPS sortant fonctionnel depuis le serveur WordPress vers l'API AutoScout24 et vers les hébergeurs d'images référencés dans la réponse de l'API.
• Un temps d'exécution PHP suffisant. Le planificateur augmente la limite de temps à 300 secondes via set_time_limit(300) pour les exécutions cron et REST ; certains hébergeurs peuvent outrepasser cela.

Flux par annonce

AS24CI\Importer::upsert_post_from_listing() est la routine centrale par annonce. Le flux simplifié est le suivant :

1. Valider que l'annonce possède un id. Ignorer sinon.
2. Ignorer les annonces dont le statut API n'est pas activated ou dont le drapeau live est vide.
3. Rechercher un article de véhicule existant par Listing ID (find_post_id_by_listing_id()).
4. Exécuter la détection des modifications (voir ci-dessous). Si rien n'a changé, écrire _as24ci_last_sync et renvoyer skipped.
5. Construire le titre, l'extrait et le contenu de l'article. Si le verrou IA (_as24ci_ai_locked = 'yes') est actif, ne pas écraser l'extrait ou le contenu de l'article.
6. Insérer ou mettre à jour l'article WordPress avec le statut d'article et l'auteur configurés par défaut.
7. Écrire les postmeta de rétrocompatibilité : _as24ci_listing_id, _as24ci_seller_id, _as24ci_last_modified (lorsque l'API le fournit) et _as24ci_last_sync.
8. S'assurer que le slug se termine par le Listing ID (ensure_slug_has_listing_id()).
9. Mapper le payload de l'annonce via AS24CI\Mapper::map_listing_to_post() afin que les champs typés soient écrits dans la table as24_vehicles.
10. Récupérer les équipements via Client::get_listing_equipment() et les mapper à l'article via Mapper::map_equipment_to_post(). Les erreurs sont journalisées mais ne font pas échouer l'importation de l'annonce.
11. Importer les images (sous réserve de l'activation de as24ci_import_images et de la limite as24ci_max_images). Le flux d'images est décrit en détail dans Image Importer And Queue.
12. Mettre à jour _as24ci_content_hash et _as24ci_original_description.
13. Déclencher l'action as24ci_vehicle_imported avec l'ID de l'article, l'annonce API brute et un booléen $is_update.
14. Renvoyer l'une des chaînes inserted, updated, skipped ou error (en cas d'échec de wp_insert_post / wp_update_post).

Détection des modifications

L'importateur ignore les annonces qui n'ont pas changé depuis l'exécution précédente, en utilisant deux vérifications en cascade :

• Principale : le champ lastModifiedDate renvoyé par l'API. Si la valeur postmeta locale _as24ci_last_modified correspond à la valeur distante, l'annonce est traitée comme inchangée. L'importateur actualise tout de même _as24ci_last_sync afin que la logique de synchronisation complète sache que l'annonce existe à distance.
• De secours : lorsque lastModifiedDate est manquant, l'importateur calcule un MD5 du payload encodé en JSON et le compare au _as24ci_content_hash stocké.

La détection des modifications d'images fonctionne de manière indépendante et est décrite dans la documentation de l'importateur d'images.

Verrou IA

Lorsque _as24ci_ai_locked est 'yes', l'importateur conserve les valeurs existantes de post_content et post_excerpt afin que les textes générés par l'IA survivent à une ré-importation. Tous les autres champs, attributions de taxonomies, équipements et images sont toujours mis à jour. La description originale de l'API est également conservée séparément dans _as24ci_original_description.

Stabilité du slug

ensure_slug_has_listing_id() met à jour le slug de l'article pour qu'il se termine par -<listing_id> chaque fois que le slug change. Cela maintient les URL stables lors des ré-importations et évite les redirections accidentelles lorsque les titres changent.

Opérations groupées

AS24CI\Importer expose les méthodes de haut niveau suivantes :

• get_seller_ids() — renvoie la liste nettoyée des Seller IDs configurés.
• get_all_preview_listings_for_seller( $seller_id, $max_pages = 20, $page_size = 50 ) — pagine à travers l'API et renvoie l'ensemble complet des annonces activées et en ligne pour un seul vendeur.
• preview_listings_for_seller( $seller_id, $page = 1, $per_page = 50 ) — aperçu paginé utilisé par l'interface utilisateur de l'assistant.
• import_selected_listings( $seller_id, $listing_ids, $max_vehicles = 0 ) — importe les Listing IDs donnés. Respecte le budget $max_vehicles ; les véhicules ignorés ne consomment pas de budget.
• import_all_for_seller( $seller_id, $max_vehicles = 0 ) — récupère la liste complète d'aperçu pour un vendeur et la délègue à import_selected_listings(). Renvoie les totaux ainsi que listing_ids (l'ensemble complet vu lors de cette exécution) et api_active (le nombre d'annonces actives renvoyées par l'API).
• full_sync_after_import( array $remote_listing_ids ) — supprime les articles locaux as24ci_car dont le _as24ci_listing_id n'est pas dans le jeu distant donné. Ignoré si le jeu distant est vide par mesure de sécurité contre une suppression accidentelle complète.
• hard_delete_listing( $listing_id ) — suppression destructive manuelle pour une seule annonce ; passe par le même nettoyage Vehicle_Deleter que la suppression native de WordPress.

La version « All-in-One » du plugin n'impose aucune limite d'annonces ; get_free_import_limit() et get_free_slots_left() renvoient PHP_INT_MAX.

Suppression de véhicule

Chaque chemin de suppression permanente passe par AS24CI\Vehicle_Deleter :

• Suppression permanente native de WordPress dans la liste des véhicules (Cars).
• Synchronisation complète de l'importateur (full_sync_after_import()).
• Actions groupées (AS24CI\Bulk_Actions).
• Importer::hard_delete_listing() manuel.

Le suppresseur s'exécute sur before_delete_post / deleted_post et :

• Supprime les pièces jointes suivies dans _as24ci_image_ids.
• Supprime la ligne correspondante dans {$wpdb->prefix}as24_vehicles.
• Déclenche l'action as24ci_vehicle_deleted.

Les pièces jointes manuelles de la galerie (_as24ci_manual_image_ids) et les autres pièces jointes non suivies par l'importateur sont intentionnellement conservées.

Hooks publics

Le moteur d'importation déclenche les hooks suivants. Vérifiez les signatures des hooks dans la version actuelle du plugin avant de vous y fier.

Le plugin lit également le filtre as24ci_webp_quality lors de la conversion des images ; voir la documentation de l'importateur d'images.

Référence de configuration

Notes opérationnelles

• L'importateur ne s'interrompt jamais sur une seule mauvaise annonce. Les erreurs de wp_insert_post, wp_update_post, Client::get_listing_equipment et de l'importateur d'images sont journalisées via AS24CI\Logger et comptabilisées mais n'interrompent pas l'exécution.
• La détection des modifications signifie qu'une ré-importation complète d'un catalogue inchangé est peu coûteuse : la plupart des annonces sont ignorées et les téléchargements d'images ne sont pas relancés.
• Le mappeur écrit dans la table as24_vehicles via le dépôt, et non dans wp_postmeta, à l'exception du petit ensemble de clés de rétrocompatibilité documenté dans Data Model.
• La synchronisation complète est optionnelle. Si as24ci_full_sync est activé, assurez-vous que les Seller IDs configurés couvrent l'intégralité du catalogue que vous souhaitez conserver en ligne ; les véhicules dont les annonces disparaissent de l'API sont définitivement supprimés.
• La journalisation détaillée produit des lignes de journal détaillées et augmente rapidement sur les grands catalogues. Le plugin impose une limite de journal de 10 Mo avec rotation ; ajustez la journalisation détaillée pour équilibrer les diagnostics et le stockage.

Dépannage

• Aucun véhicule importé. Confirmez les identifiants API, que as24ci_seller_ids n'est pas vide, et que l'API renvoie des annonces avec status = activated et live = true. Vérifiez le journal du plugin pour les erreurs HTTP de AS24CI\Client.
• Les annonces restent au statut draft. Le plugin définit par défaut as24ci_default_post_status sur draft afin que les administrateurs puissent vérifier les correspondances. Modifiez l'option sur publish une fois que vous êtes satisfait, ou publiez les véhicules individuellement depuis la liste d'administration.
• Des ré-importations répétées continuent de mettre à jour les mêmes véhicules. Vérifiez que l'API fournit un lastModifiedDate stable. Lorsqu'il est manquant, le hachage de contenu de secours détecte les modifications ; le hachage changera chaque fois que le payload de l'API change pour une raison quelconque.
• Un véhicule a disparu après une exécution cron. Vérifiez si as24ci_full_sync est activé. Lorsque la synchronisation complète est activée, toute annonce manquante dans l'API est définitivement supprimée (ses pièces jointes importées comprises).
• Importer ran but no images were downloaded. Vérifiez as24ci_import_images et as24ci_max_images. Dans les exécutions cron/REST avec as24ci_cron_image_queue = 1, seule la première image est téléchargée immédiatement et le reste est différé vers le gestionnaire de file d'attente d'images.
• Skipping listing_id=… : lastModifiedDate unchanged. C'est la ligne de journal détaillée attendue pour les annonces inchangées ; elle confirme que la détection des modifications fonctionne.

---

---

Documents connexes

• Importateur d'images et file d'attente
• Événements Cron et planificateur
• Aperçu de l'architecture
• Modèle de données
• Schéma de la base de données
• Aperçu de la section