Import Engine

Dit document beschrijft hoe de ADP Car Market Hub-plugin voertuigadvertenties importeert van de AutoScout24 API naar WordPress. Het behandelt de verantwoordelijkheden van de importer-klassen, de workflow per advertentie, wijzigingsdetectie, verwijdering bij volledige synchronisatie en de openbare hook die wordt geactiveerd nadat een voertuig is geïmporteerd.

Wanneer u dit document moet gebruiken

Lees dit document als u het volgende wilt doen:

• Begrijpen wat er gebeurt tijdens een import-run.
• Diagnosticeren waarom een voertuig is toegevoegd, bijgewerkt, overgeslagen of verwijderd.
• Een aangepaste integratie bouwen die reageert op imports via de as24ci_vehicle_imported-actie.
• Capaciteits- of hostingvereisten plannen voor grote catalogi.

Zie Cron-gebeurtenissen en planner voor details over planning en cron. Zie Afbeeldingsimporter en wachtrij voor de verwerking van afbeeldingen.

Overzicht

De import engine bestaat uit verschillende klassen die samenwerken:

• AS24CI\Client — voert geauthenticeerde HTTP-verzoeken uit naar de AutoScout24 API, beheert OAuth-tokens (inclusief de as24ci_access_token transient cache) en biedt hulpprogramma's voor voorbeeldpagina's en uitrusting per advertentie.
• AS24CI\Importer — coördineert de import per advertentie. Beslist of er moet worden toegevoegd, bijgewerkt of overgeslagen en schrijft de post, postmeta en afbeeldingsreferenties van het voertuig. Is eigenaar van de wijzigingsdetectie.
• AS24CI\Mapper — mapt de ruwe AutoScout24-payload naar de velden die zijn opgeslagen in de as24_vehicles-tabel via AS24CI\Vehicle_Repository. Onderhoudt achterwaarts compatibele postmeta-sleutels.
• AS24CI\Vehicle_Repository — slaat voertuigveldgegevens op in de specifieke {$wpdb->prefix}as24_vehicles-tabel.
• AS24CI\Image_Importer — downloadt afbeeldingen, converteert ze optioneel naar WebP en koppelt ze aan de voertuigpost. Zie Afbeeldingsimporter en wachtrij.
• AS24CI\Scheduler — verpakt Importer::import_all_for_seller() in een vergrendelde, tegen herhaling beveiligde runner die wordt gebruikt door WP-Cron, het REST-cron-endpoint en de handmatige "Nu uitvoeren"-knop.

Dezelfde Importer-instantie wordt hergebruikt door de handmatige Batch-Wizard, de cron-runner en het REST-cron-endpoint.

Vereisten of randvoorwaarden

Voordat u een import uitvoert, heeft u het volgende nodig:

• Geldige AutoScout24 API-inloggegevens geconfigureerd in de plugin (as24ci_base_url, as24ci_token_url, as24ci_client_id, as24ci_client_secret, as24ci_token_audience).
• Een of meer Seller ID's in as24ci_seller_ids (kommagescheiden).
• Een WordPress-gebruiker die is aangewezen als de standaard auteur van de post (as24ci_default_post_author); imports vallen terug op de huidige gebruiker wanneer er geen standaard is ingesteld.
• Werkende uitgaande HTTPS-toegang vanaf de WordPress-server naar de AutoScout24 API en naar de afbeeldingshosts waarnaar wordt verwezen in de API-respons.
• Voldoende PHP-uitvoeringstijd. De planner verhoogt de tijdslimiet naar 300 seconden via set_time_limit(300) voor cron- en REST-runs; sommige hosts kunnen dit overschrijven.

Workflow per advertentie

AS24CI\Importer::upsert_post_from_listing() is de centrale routine per advertentie. De vereenvoudigde workflow is:

1. Valideer of de advertentie een id heeft. Sla anders over.
2. Sla advertenties over waarvan de API-status niet activated is of waarvan de live-vlag leeg is.
3. Zoek een bestaande voertuigpost op via de Listing ID (find_post_id_by_listing_id()).
4. Voer wijzigingsdetectie uit (zie hieronder). Als er niets is gewijzigd, schrijf dan _as24ci_last_sync en retourneer skipped.
5. Bouw de titel, de samenvatting en de inhoud van de post op. Als de AI Lock (_as24ci_ai_locked = 'yes') actief is, overschrijf dan de samenvatting of inhoud van de post niet.
6. Voeg de WordPress-post toe of werk deze bij met de geconfigureerde standaard post-status en auteur.
7. Schrijf achterwaarts compatibele postmeta: _as24ci_listing_id, _as24ci_seller_id, _as24ci_last_modified (wanneer de API deze levert) en _as24ci_last_sync.
8. Zorg ervoor dat de slug eindigt met de Listing ID (ensure_slug_has_listing_id()).
9. Map de advertentie-payload via AS24CI\Mapper::map_listing_to_post() zodat de getypeerde velden naar de as24_vehicles-tabel worden geschreven.
10. Haal uitrusting op via Client::get_listing_equipment() en map deze naar de post via Mapper::map_equipment_to_post(). Fouten worden gelogd maar zorgen er niet voor dat de advertentie mislukt.
11. Importeer afbeeldingen (afhankelijk van de as24ci_import_images-schakelaar en de limiet van as24ci_max_images). De afbeeldingsworkflow wordt in detail beschreven in Afbeeldingsimporter en wachtrij.
12. Werk _as24ci_content_hash en _as24ci_original_description bij.
13. Activeer de as24ci_vehicle_imported-actie met de post ID, de ruwe API-advertentie en een boolean $is_update.
14. Retourneer een van de strings inserted, updated, skipped of error (bij mislukken van wp_insert_post / wp_update_post).

Wijzigingsdetectie

De importer slaat advertenties over die niet zijn gewijzigd sinds de vorige run, met behulp van twee opeenvolgende controles:

• Primair: het veld lastModifiedDate dat door de API wordt geretourneerd. Als de lokale _as24ci_last_modified-postmeta overeenkomt met de externe waarde, wordt de advertentie als ongewijzigd beschouwd. De importer vernieuwt nog steeds _as24ci_last_sync zodat de logica voor volledige synchronisatie weet dat de advertentie extern bestaat.
• Fallback: wanneer lastModifiedDate ontbreekt, berekent de importer een MD5 van de JSON-gecodeerde payload en vergelijkt deze met de opgeslagen _as24ci_content_hash.

De wijzigingsdetectie voor afbeeldingen werkt onafhankelijk en wordt beschreven in de documentatie van de afbeeldingsimporter.

AI Lock

Wanneer _as24ci_ai_locked 'yes' is, behoudt de importer de bestaande post_content en post_excerpt zodat door AI gegenereerde teksten behouden blijven bij een herimport. Alle andere velden, taxonomie-toewijzingen, uitrusting en afbeeldingen worden nog steeds bijgewerkt. De originele API-beschrijving wordt ook apart bewaard in _as24ci_original_description.

Slug-stabiliteit

ensure_slug_has_listing_id() werkt de post-slug bij zodat deze eindigt met -<listing_id> telkens wanneer de slug verandert. Dit houdt URL's stabiel tijdens herimports en voorkomt onbedoelde omleidingen wanneer titels veranderen.

Bulkbewerkingen

AS24CI\Importer stelt de volgende methoden op hoog niveau beschikbaar:

• get_seller_ids() — retourneert de opgeschoonde lijst van geconfigureerde Seller ID's.
• get_all_preview_listings_for_seller( $seller_id, $max_pages = 20, $page_size = 50 ) — blader door de API en retourneert de volledige set van geactiveerde, live advertenties voor een enkele verkoper.
• preview_listings_for_seller( $seller_id, $page = 1, $per_page = 50 ) — gepagineerd voorbeeld gebruikt door de UI van de wizard.
• import_selected_listings( $seller_id, $listing_ids, $max_vehicles = 0 ) — importeert de opgegeven Listing ID's. Respecteert het $max_vehicles-budget; overgeslagen voertuigen verbruiken geen budget.
• import_all_for_seller( $seller_id, $max_vehicles = 0 ) — haalt de volledige voorbeeldlijst op voor een verkoper en delegeert naar import_selected_listings(). Retourneert tellingen plus listing_ids (de volledige set die tijdens deze run is gezien) en api_active (aantal actieve advertenties dat de API heeft geretourneerd).
• full_sync_after_import( array $remote_listing_ids ) — verwijdert lokale as24ci_car-posts waarvan de _as24ci_listing_id zich niet in de opgegeven externe set bevindt. Wordt overgeslagen als de externe set leeg is als veiligheidsmaatregel tegen onbedoeld wissen.
• hard_delete_listing( $listing_id ) — handmatige destructieve verwijdering voor een enkele advertentie; doorloopt dezelfde Vehicle_Deleter opschoning als de systeemeigen WordPress-verwijdering.

De "All-in-One"-versie van de plugin legt geen advertentielimiet op; get_free_import_limit() en get_free_slots_left() retourneren PHP_INT_MAX.

Voertuigverwijdering

Elk permanent verwijderingstraject verloopt via AS24CI\Vehicle_Deleter:

• Systeemeigen WordPress "Permanent verwijderen" in de Cars-lijst.
• Volledige synchronisatie van de importer (full_sync_after_import()).
• Bulkacties (AS24CI\Bulk_Actions).
• Handmatige Importer::hard_delete_listing().

De verwijderaar wordt uitgevoerd op before_delete_post / deleted_post en:

• Verwijdert bijlagen die worden bijgehouden in _as24ci_image_ids.
• Verwijdert de bijbehorende rij in {$wpdb->prefix}as24_vehicles.
• Activeer de as24ci_vehicle_deleted-actie.

Handmatige galerijbijlagen (_as24ci_manual_image_ids) and andere bijlagen die niet door de importer worden bijgehouden, worden opzettelijk bewaard.

Openbare hooks

De import engine activeert de volgende hooks. Controleer de hook-signaturen in de huidige plugin-versie voordat u er op vertrouwt.

De plugin leest ook het as24ci_webp_quality-filter bij het converteren van afbeeldingen; zie de documentatie van de afbeeldingsimporter.

Configuratiereferentie

Operationele opmerkingen

• De importer loopt nooit vast op een enkele slechte advertentie. Fouten van wp_insert_post, wp_update_post, Client::get_listing_equipment en de afbeeldingsimporter worden gelogd via AS24CI\Logger en geteld, maar breken de run niet af.
• Wijzigingsdetectie betekent dat een volledige herimport van een ongewijzigde catalogus goedkoop is: de meeste advertenties worden overgeslagen en downloads van afbeeldingen worden niet opnieuw uitgevoerd.
• De mapper schrijft naar de as24_vehicles-tabel via de repository, niet naar wp_postmeta, behalve voor de kleine achterwaarts compatibele sleutelset gedocumenteerd in Datamodel.
• Volledige synchronisatie is opt-in. Als as24ci_full_sync is ingeschakeld, zorg er dan voor dat de geconfigureerde Seller ID's de volledige catalogus beslaan die u online wilt houden; voertuigen waarvan de advertenties uit de API verdwijnen, worden permanent verwijderd.
• Uitgebreide logboekregistratie (verbose logging) produceert gedetailleerde logregels en groeit snel bij grote catalogi. De plugin handhaaft een loglimiet van 10 MB met rotatie; pas uitgebreide logboekregistratie aan om diagnostiek in balans te houden met opslagruimte.

Probleemoplossing

• Geen voertuigen geïmporteerd. Controleer de API-inloggegevens, of as24ci_seller_ids niet leeg is en of de API advertenties retourneert met status = activated en live = true. Controleer het plugin-logboek op HTTP-fouten van AS24CI\Client.
• Advertenties blijven in de status draft. De plugin stelt as24ci_default_post_status standaard in op draft zodat beheerders toewijzingen kunnen controleren. Wijzig de optie naar publish zodra u tevreden bent, of publiceer individuele voertuigen vanuit de beheerderslijst.
• Herhaalde herimports blijven dezelfde voertuigen bijwerken. Controleer of de API een stabiele lastModifiedDate levert. Wanneer deze ontbreekt, detecteert de fallback-inhoudshash wijzigingen; de hash verandert telkens wanneer de API-payload om welke reden dan ook verandert.
• Een voertuig is verdwenen na een cron-run. Controleer of as24ci_full_sync is ingeschakeld. Met volledige synchronisatie ingeschakeld, wordt elke advertentie die ontbreekt in de API permanent verwijderd (inclusief de geïmporteerde bijlagen).
• Importer ran but no images were downloaded. Controleer as24ci_import_images en as24ci_max_images. In cron/REST-runs met as24ci_cron_image_queue = 1 wordt alleen de eerste afbeelding onmiddellijk gedownload en wordt de rest uitgesteld naar de afbeeldingswachtrij-worker.
• Skipping listing_id=… : lastModifiedDate unchanged. Dit is de verwachte uitgebreide logregel voor ongewijzigde advertenties; het bevestigt dat de wijzigingsdetectie werkt.

---

Gerelateerde documenten

• Image Importer And Queue
• Cron Events And Scheduler
• Architecture Overview
• Data Model
• Database Schema
• Section overview