REST Endpoint-referentie

Deze bijlage bevat een overzicht van de REST API-routes die door de ADP Car Market Hub-plugin zijn geregistreerd onder de as24ci/v1-namespace.

Wanneer u dit document moet gebruiken

Gebruik deze referentie wanneer u een plugin-endpoint moet aanroepen, wanneer u onverwachte 403/404-antwoorden diagnosticeert, of wanneer u een integratie documenteert. Zie REST API Endpoints voor de conceptuele beschrijving van elk endpoint.

Overzicht

Alle routes die door de plugin worden geregistreerd, maken gebruik van de WordPress REST API en delen de namespace as24ci/v1. De volledige URL van elk endpoint is de WordPress REST-root gevolgd door de route, doorgaans https://example.com/wp-json/as24ci/v1/....

De endpoints vallen uiteen in vijf groepen:

1. Openbare voertuiggegevens (/vehicles, /vehicles/{id}) — standaard uitgeschakeld; beveiligd door as24ci_rest_api_enabled.
2. Favorieten-helper (/favorites) — gebruikt door de favorietenpagina op de frontend.
3. Analytics-tracking (/analytics/track) — gebruikt door het frontend-script.
4. Cron-importtrigger (/cron-import) — beveiligd met een token; gebruikt door externe planners.
5. Licentieverversingssignaal (/license-refresh-signal) — gebruikt door het API Platform om de site te vragen de licentie opnieuw te valideren.

Overzicht van endpoints

GET /as24ci/v1/vehicles

Gepagineerde, filterbare lijst van geïmporteerde voertuigen waarvan de post-status publish is.

Query-parameters:

Antwoord (structuur):

{
  "vehicles": [
    {
      "id": 0, "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
}

Het veld image is de middelgrote/grote afmeting van de uitgelichte afbeelding (lege string als er geen is). Het veld currency valt terug op as24ci_default_currency wanneer er geen valuta per voertuig is opgeslagen.

GET /as24ci/v1/vehicles/{id}

Volledige details voor een enkel voertuig.

• Pad-parameter: id — positief geheel getal; gevalideerd en gecast via absint.
• Authenticatie: geen (openbaar). Zelfde beveiliging als het lijst-endpoint.
• Antwoord: alle velden uit het lijst-antwoord plus description, images (array van bijlage-URL's op large-formaat, die handmatige en geïmporteerde afbeeldingen combineert en terugvalt op de uitgelichte afbeelding), equipment_standard, equipment_optional en seller.
• Fouten: 404 as24ci_vehicle_not_found wanneer de post niet bestaat, niet de as24ci_car CPT is, of niet is gepubliceerd.

POST /as24ci/v1/favorites

Hydrateert de favorieten van de bezoeker met actuele voertuiggegevens voor ID's die zijn opgeslagen in de lokale opslag van de browser.

• Authenticatie: geen (openbaar). Altijd geregistreerd.
• Body: JSON-object met ids — een array van post-ID's. Opgeschoond tot een unieke lijst van positieve gehele getallen; gemaximeerd op 50 ID's per verzoek.
• Antwoord: { "vehicles": [ ... ] }.
• Opmerkingen: Alleen gepubliceerde voertuigen worden geretourneerd. Berichten waar de bezoeker geen toegang meer toe heeft (verwijderd, concept, onjuist post-type) worden geruisloos weggelaten.

POST /as24ci/v1/analytics/track

Ontvangt analytics-gebeurtenissen van de trackingpixel aan de frontend.

• Authenticatie: geen (openbaar). Altijd geregistreerd.
• Body-parameters:
• post_id — integer ≥ 0. Standaard 0.
• event_type — een van view, view_archive, view_compare, view_favorites, filter_search, contact_open, lead_sent.
• extra_data — optionele opgeschoonde string. Voor filter_search moet dit een JSON-object zijn dat de actieve filter-sleutel/waardeparen bevat.
• Antwoord: { "tracked": true } bij succes, of { "tracked": false } met HTTP 400 wanneer de gebeurtenis een voertuigpost vereist die niet bestaat of niet is gepubliceerd.
• Opmerkingen: Bewust permissief zodat anonieme bezoekers gebeurtenissen kunnen verzenden. Vertrouw hier niet op voor sluitende bedrijfsgegevens.

GET /as24ci/v1/cron-import

Met een token beveiligd endpoint dat de gedeelde importroutine uitvoert. Delegeert naar dezelfde Scheduler::run_import()-methode die wordt gebruikt door de WP-Cron-hook en de handmatige "Nu triggeren"-beheerdersknop.

• Authenticatie: bearer-token. Geef het token op via de HTTP-header Authorization: Bearer <token> (voorkeur — houdt het token buiten de toegangslogs) of de query-parameter ?token=<token>. De vergelijking maakt gebruik van hash_equals() om timing-aanvallen te beperken.
• Token-opslag: as24ci_cron_token-optie. Genereer of roteer deze via Import & Limieten in het plugin-beheer.
• Antwoorden:
• 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 runner weigerde een tweede te starten.
• 500 wanneer de runner een uitzondering heeft gegenereerd.
• Bijwerking: Een succesvolle authenticatie werkt as24ci_last_external_cron_run bij, wat het tabblad Systeem & Hulp gebruikt om te bevestigen dat de externe cron de site bereikt. Het bezoeken van een willekeurige URL met ?as24ci_cron=1 werkt deze tijdstempel ook bij via de heartbeat-hook op init.

Voorbeeld van een externe cron-aanroep (placeholder — vervang door uw eigen host en een gegenereerd token):

0 * * * * curl -fsS -H "Authorization: Bearer YOUR_TOKEN" \
  "https://example.com/wp-json/as24ci/v1/cron-import?as24ci_cron=1"

POST /as24ci/v1/license-refresh-signal

Lichtgewicht signaal-endpoint waarmee het API Platform de site kan vragen om de licentie out-of-band opnieuw te valideren (bijvoorbeeld na een wijziging van het abonnement). Onvoorwaardelijk geregistreerd zodat het platform dit altijd kan bereiken; het is niet afgeschermd achter de openbare voertuig-REST API-optie.

• Authenticatie: op signalen gebaseerd vertrouwensmodel. Authenticatie wordt afgehandeld binnen de callback in plaats van door een permission_callback; het verzoek moet JSON zijn en wordt gevalideerd tegen de verwachte signaalstructuur.
• Body: JSON-object. Veilige, niet-geheime correlatievelden (request_id, event) worden alleen teruggestuurd voor tracering.
• Antwoorden:
• 405 method_not_allowed wanneer het verzoek niet POST is.
• 400 invalid_content_type wanneer de body geen JSON is, of 400 invalid_json wanneer de body niet kan worden geparsed.
• 200 wanneer het signaal wordt geaccepteerd.
• Eigenaar: AS24CI\License_Refresh_Signal.

Operationele opmerkingen

• De openbare voertuig-endpoints voeren standaard WP_Query-aanroepen uit en respecteren de normale WordPress-objectcaching. Herhaalde identieke verzoeken profiteren van de post- en post-meta-caches.
• Numerieke filters dragen bij aan een meta_query. Zorg er bij grote catalogi voor dat de onderliggende meta-sleutels op databaseniveau zijn geïndexeerd als u veel verkeer verwacht. Controleer de indexeringsstrategie in de huidige plugin-versie voordat u live gaat.
• Het lijst-endpoint past update_postmeta_cache() toe op de geretourneerde posts om de responstijden voorspelbaar te houden.
• Het favorieten-endpoint stelt een harde limiet van 50 ID's per verzoek in om misbruik te voorkomen.
• Het cron-import-endpoint stelt nocache_headers() in, zodat caching-proxies de geplande uitvoeringen niet verstoren.
• Mooie permalinks worden aanbevolen voor REST-URL's in padstijl. Met eenvoudige permalinks zijn de endpoints nog steeds bereikbaar via ?rest_route=.

Problemen oplossen

• /vehicles retourneert 404. De openbare API is uitgeschakeld. Stel as24ci_rest_api_enabled in op '1' in Instellingen → SEO & Integraties (of via WP-CLI / update_option).
• /cron-import retourneert 403. Ofwel is er geen token geconfigureerd (as24ci_cron_token is leeg — het antwoordbericht bevestigt dit), ofwel komt het opgegeven token niet overeen. Genereer een nieuw token in het beheer 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.
• Lege vehicles-array op het lijst-endpoint zonder filters. Er zijn geen voertuigen gepubliceerd, of de catalogus is nog niet geïmporteerd. Controleer het scherm Import & Limieten en de importlogs.
• HTTP 400 op /analytics/track. De gebeurtenis vereist een gepubliceerde voertuigpost, maar post_id verwijst naar een concept, verwijderde post of een post die geen voertuig is.

Gerelateerde documenten

• REST API Endpoints
• REST API For Developers
• Cron Hook Reference
• Webhook Event Reference
• Settings Reference