REST API-endpoints

Dit document beschrijft de REST API-routes die door de ADP Car Market Hub-plugin zijn geregistreerd onder de as24ci/v1-namespace, inclusief hun methoden, parameters, authenticatiemodel en beoogde gebruik.

Wanneer u dit document moet gebruiken

Lees dit document als u het volgende moet doen:

• Een aangepaste integratie bouwen die voertuiggegevens van de plugin via HTTP ophaalt.
• Imports activeren vanaf een externe planner in plaats van WP-Cron.
• Begrijpen welke endpoints openbaar zijn, welke worden beheerd door een door de beheerder gecontroleerde schakelaar en welke een token vereisen.
• Onverwachte 403 / 404-reacties van de REST-routes van de plugin diagnosticeren.

Voor de AJAX-interface (admin-ajax.php), zie AJAX-acties. Voor uitgaande HTTP-oproepen naar externe systemen, zie Webhooks.

Overzicht

Alle routes die door de plugin worden geregistreerd, maken gebruik van de WordPress REST API en delen de namespace as24ci/v1. Endpoints vallen uiteen in vier groepen:

1. Openbare voertuiggegevens — alleen-lezen listing- en detail-endpoints. Standaard uitgeschakeld; moet worden ingeschakeld door een beheerder.
2. Favorieten-helper — gebruikt door de favorietenpagina op de frontend om voertuiggegevens op te halen voor ID's die de bezoeker lokaal heeft opgeslagen.
3. Analytics-trackingpixel — accepteert lichtgewicht gebeurtenismeldingen van het frontend-script.
4. Cron-importtrigger — met token beveiligd endpoint dat de gedeelde importroutine op aanvraag uitvoert.
5. Licentieverversingssignaal — endpoint dat alleen signalen ontvangt en dat door het ADP Car Market Hub API Platform wordt aangeroepen, zodat de plugin onmiddellijk de gezaghebbende licentie- / functierechtenstatus opnieuw ophaalt.

De volledige basis-URL van elk endpoint is de WordPress REST-root gevolgd door de route. Op een typische site is dit https://example.com/wp-json/as24ci/v1/....

Vereisten of randvoorwaarden

• WordPress met de REST API ingeschakeld (de standaardinstelling van WordPress).
• Pretty permalinks voor REST-URL's in padstijl. Met eenvoudige permalinks zijn de endpoints nog steeds bereikbaar via ?rest_route=.
• Voor de openbare voertuig-endpoints: de optie as24ci_rest_api_enabled moet zijn ingesteld op 1. Tot die tijd zijn de routes niet geregistreerd en retourneert elk verzoek een 404 van WordPress.
• Voor het cron-import-endpoint: er moet een cron-token worden gegenereerd in het tabblad Import & Limieten in het beheergedeelte.

Endpoint-referentie

GET /as24ci/v1/vehicles

Retourneert een gepagineerde, filterbare lijst van geïmporteerde voertuigen waarvan de CPT-status publish is.

• Auth: geen (openbaar). Route is alleen geregistreerd wanneer as24ci_rest_api_enabled gelijk is aan 1.
• Queryparameters:
• page — geheel getal ≥ 1. Standaard 1.
• per_page — geheel getal tussen 1 en 100. Standaard 10.
• make, model — exacte overeenkomst met de bijbehorende meta-keys.
• fuel_type — LIKE overeenkomst met de gemapte brandstoftype meta-key.
• year_min, year_max — numeriek bereik voor _as24ci_year.
• price_min, price_max — numeriek bereik voor _as24ci_price.
• orderby — een van date, price, mileage, title. Standaard date.
• order — asc of desc (niet hoofdlettergevoelig). Standaard desc.
• Vorm van de respons: ``json { "vehicles": [ { "id": 123, "title": "...", "url": "...", "image": "...", "make": "...", "model": "...", "year": 0, "price": 0, "currency": "EUR", "mileage": 0, "condition": "...", "fuel_type": "...", "transmission": "...", "body_type": "...", "color": "...", "doors": 0, "horse_power": 0, "vin": "...", "listing_id": "..." } ], "total": 0, "pages": 0, "page": 1, "per_page": 10 } ``
• Opmerkingen: Het veld image is de middelgrote/grote WordPress-grootte van de uitgelichte afbeelding (lege string als er geen thumbnail bestaat). Het veld currency valt terug op de waarde van de optie as24ci_default_currency wanneer er geen valuta per voertuig is opgeslagen.

GET /as24ci/v1/vehicles/<id>

Retourneert de volledige details van een enkel voertuig.

• Auth: geen (openbaar). Zelfde toegangscontrole als het lijst-endpoint.
• Padparameter: id — positief geheel getal. Gevalideerd en geconverteerd naar absint.
• Respons: Alle velden uit de lijstrespons plus:
• description — gebruikt de WordPress samenvatting indien aanwezig, anders de ingekorte inhoud van het bericht (≈55 woorden).
• images — array van bijlage-URL's op de large-grootte, waarbij handmatige galerij-afbeeldingen (_as24ci_manual_image_ids) en geïmporteerde afbeeldingen (_as24ci_image_ids) worden gecombineerd; valt terug op de uitgelichte afbeelding wanneer beide leeg zijn.
• equipment_standard, equipment_optional — arrays van strings.
• seller — weergavenaam van de dealer.
• Fouten:
• 404 (as24ci_vehicle_not_found) wanneer het bericht niet bestaat, niet de as24ci_car CPT is, of niet is gepubliceerd.

POST /as24ci/v1/favorites

Gebruikt door de favorietenpagina op de frontend om samenvattende voertuiggegevens op te halen voor de ID's die de bezoeker heeft opgeslagen in de lokale browseropslag.

• Auth: geen (openbaar). Altijd geregistreerd.
• Body: JSON-object met ids, een array van post-ID's. Gevalideerd als een array; opgeschoond tot een unieke lijst van positieve gehele getallen. Er worden maximaal 50 ID's per oproep verwerkt.
• Respons: { "vehicles": [ ... ] }.
• Opmerkingen: Het endpoint leest alleen gepubliceerde voertuigen. Berichten waar de bezoeker geen toegang meer toe heeft (verwijderd, concept, onjuist berichttype) worden geruisloos weggelaten.

POST /as24ci/v1/analytics/track

Ontvangt weergave-, archiefweergave-, vergelijkingsweergave-, favorietenweergave-, zoekfilter-, contact-open- en lead-verzonden-gebeurtenissen van de analytics-trackingpixel.

• Auth: geen (openbaar). Altijd geregistreerd.
• Bodyparameters:
• post_id — geheel getal ≥ 0. Standaard 0.
• event_type — moet een van de toegestane gebeurtenisnamen zijn: view, view_archive, view_compare, view_favorites, filter_search, contact_open, lead_sent.
• extra_data — optionele opgeschoonde string. Voor filter_search moet de string een JSON-object zijn dat de actieve filter-sleutel/waardeparen bevat; de server past dezelfde minimalisatielogica toe die wordt gebruikt door directe PHP-tracking voordat deze wordt opgeslagen.
• Respons: { "tracked": true } bij succes, { "tracked": false } met HTTP 400 wanneer de gebeurtenis een voertuigbericht vereist dat niet bestaat of niet is gepubliceerd.
• Opmerkingen: Dit endpoint is bewust tolerant, zodat anonieme bezoekers analytics-gebeurtenissen kunnen verzenden. Vertrouw hier niet op voor gezaghebbende bedrijfsgegevens; zie Analytics-tracking voor opmerkingen over bewaring en privacy.

GET /as24ci/v1/cron-import

Met token beveiligd endpoint dat de gedeelde importroutine uitvoert. Het delegeert naar dezelfde Scheduler::run_import()-methode die wordt gebruikt door de WP-Cron-hook en de beheerknop Nu starten.

• Auth: bearer-token. Geef het token op via de HTTP-header Authorization: Bearer <token> (bij voorkeur — houdt het token buiten de toegangslogs) of de queryparameter ?token=<token>.
• Tokenopslag: opgeslagen in de optie as24ci_cron_token. Genereer of roteer het via Import & Limieten in het beheergedeelte van de plugin.
• Responsen:
• 403 wanneer er geen token is geconfigureerd of het opgegeven token niet overeenkomt.
• 200 met { "success": true, "message": "...", "counts": { ... } } bij een succesvolle uitvoering.
• 429 met success: false wanneer er al een andere import actief is en de uitvoerder heeft geweigerd een tweede te starten.
• 500 wanneer de uitvoerder een uitzondering heeft gegenereerd.
• Bijwerking: een succesvolle authenticatie werkt de optie as24ci_last_external_cron_run bij, die door het tabblad Systeem & Hulp wordt gebruikt om te bevestigen dat de externe cron de site bereikt.

POST /as24ci/v1/license-refresh-signal

Endpoint dat alleen signalen ontvangt en dat door het ADP Car Market Hub API Platform wordt aangeroepen na een wijziging in de licentie of functierechten, zodat de plugin onmiddellijk de gezaghebbende status opnieuw ophaalt. Eigendom van AS24CI\License_Refresh_Signal en onvoorwaardelijk geregistreerd (net als /cron-import), onafhankelijk van as24ci_rest_api_enabled.

• Auth: afgehandeld binnen de callback met behulp van een op vertrouwen gebaseerd model dat alleen signalen accepteert. Niets uit de verzoekbody wordt als gegevens vertrouwd; het verzoek triggert alleen License_Manager::refresh(). De handler dwingt achtereenvolgens af: POST + JSON-contenttype; een overeenkomende product_key (tegen License_Client::PRODUCT_KEY); een overeenkomende installation_uid wanneer beide partijen er een hebben; een geconfigureerde lokale licentie; een verstrekt geheim voor het verversingssignaal per installatie; een recente tijdstempel-header en ongebruikte nonce (replay-beveiliging, venster van 5 minuten); en een HMAC-SHA256-handtekening over de tijdstempel + raw body.
• Snelheidsbeperking: herhaalde signalen binnen een venster van 30 seconden worden geaccepteerd-maar-niet-ververst en beantwoord met 429, zodat een piek nooit het API Platform kan overbelasten.
• Responsen: 200 bij een getriggerde verversing; 4xx/503 voor de bovenstaande validatiefouten (403 product-/installatiemismatch, 409 niet gelicentieerd / herhaalde nonce, 401 onjuiste tijdstempel/handtekening, 503 wanneer er geen signaalgeheim is verstrekt).

Operationele opmerkingen

• De openbare voertuig-endpoints voeren standaard WP_Query-oproepen uit en respecteren de normale WordPress-objectcaching. Herhaalde identieke verzoeken profiteren van de post- en post-meta-caches.
• Numerieke filters (year_min/year_max, price_min/price_max) worden toegevoegd aan een meta_query. Zorg er bij grote catalogi voor dat de onderliggende meta-keys op databaseniveau zijn geïndexeerd als u veel verkeer verwacht. Controleer de exacte indexeringsstrategie in de huidige plugin-versie voordat u deze publiceert.
• Het lijst-endpoint past update_postmeta_cache() toe voor de geretourneerde berichten om de responstijden voorspelbaar te houden.
• Het favorieten-endpoint stelt een harde limiet in van 50 ID's per verzoek om misbruik te voorkomen en de responslading redelijk te houden.
• Het cron-import-endpoint stelt nocache_headers() in, zodat cache-proxies geplande uitvoeringen niet verstoren.
• De tokenvergelijking maakt gebruik van hash_equals() om timing-aanvallen te verminderen. Geef desondanks de voorkeur aan de Authorization: Bearer-header om te voorkomen dat het token lekt via referrer-headers, browsergeschiedenis of toegangslogs van de webserver.

Configuratiereferentie

Voor de volledige lijst met plugin-opties, zie Opslag van opties en instellingen.

Problemen oplossen

• /vehicles retourneert 404 — de openbare API is uitgeschakeld. Stel as24ci_rest_api_enabled in op '1' in Import & Limieten (of via WP-CLI / update_option).
• /cron-import retourneert 403 — ofwel er is nog geen token geconfigureerd, of de opgegeven waarde komt niet overeen. Genereer een nieuw token in het beheergedeelte en probeer het opnieuw.
• /cron-import retourneert 429 — er is al een andere import actief en een vergrendeling voorkomt een tweede gelijktijdige uitvoering. Wacht tot de huidige uitvoering is voltooid; zie Cron-gebeurtenissen en planner voor de TTL van de vergrendeling.
• Lege vehicles-array op het lijst-endpoint zonder filters — er zijn geen voertuigen gepubliceerd, of de catalogus is nog niet geïmporteerd. Controleer Import & Limieten en de importlogs.
• Onverwachte HTTP 400 op /analytics/track — de gebeurtenis vereist een gepubliceerd voertuigbericht, maar post_id verwijst naar een concept, verwijderd of niet-voertuigbericht.

Gerelateerde documenten

• AJAX-acties
• Webhooks
• Cron-gebeurtenissen en planner
• Opslag van opties en instellingen
• Analytics-tracking
• Beveiliging en mogelijkheden