REST-API-Endpunkte

Dieses Dokument beschreibt die REST-API-Routen, die vom ADP Car Market Hub-Plugin unter dem Namespace as24ci/v1 registriert werden, einschließlich ihrer Methoden, Parameter, des Authentifizierungsmodells und des Verwendungszwecks.

Wann Sie dieses Dokument verwenden sollten

Lesen Sie dieses Dokument, wenn Sie:

• Eine benutzerdefinierte Integration erstellen möchten, die Fahrzeugdaten über HTTP aus dem Plugin abruft.
• Importe über einen externen Scheduler anstelle von WP-Cron auslösen möchten.
• Verstehen möchten, welche Endpunkte öffentlich sind, welche durch eine vom Administrator gesteuerte Option geschützt sind und welche ein Token erfordern.
• Unerwartete 403- / 404-Antworten von den REST-Routen des Plugins diagnostizieren möchten.

Für die AJAX-Schnittstelle (admin-ajax.php) siehe AJAX-Aktionen. Für ausgehende HTTP-Aufrufe an externe Systeme siehe Webhooks.

Übersicht

Alle vom Plugin registrierten Routen verwenden die WordPress-REST-API und teilen sich den Namespace as24ci/v1. Die Endpunkte lassen sich in vier Gruppen einteilen:

1. Öffentliche Fahrzeugdaten – schreibgeschützte Listen- und Detail-Endpunkte. Standardmäßig deaktiviert; müssen von einem Administrator aktiviert werden.
2. Favoriten-Helfer – wird von der Frontend-Favoritenseite verwendet, um Fahrzeugdaten für IDs abzurufen, die der Besucher lokal gespeichert hat.
3. Analyse-Tracking-Pixel – empfängt schlanke Ereignisbenachrichtigungen vom Frontend-Skript.
4. Cron-Import-Trigger – Token-geschützter Endpunkt, der die gemeinsame Import-Routine bei Bedarf ausführt.
5. Lizenz-Aktualisierungssignal – reiner Signal-Endpunkt, den die ADP Car Market Hub API-Plattform aufruft, damit das Plugin seinen maßgeblichen Lizenz- / Feature-Rechte-Status neu abruft.

Die vollständige Basis-URL jedes Endpunkts ist der WordPress-REST-Root gefolgt von der Route. Auf einer typischen Website ist dies https://example.com/wp-json/as24ci/v1/....

Anforderungen oder Voraussetzungen

• WordPress mit aktivierter REST-API (der Standard bei WordPress).
• Sprechende Permalinks für REST-URLs im Pfad-Stil. Bei einfachen Permalinks sind die Endpunkte weiterhin über ?rest_route= erreichbar.
• Für die öffentlichen Fahrzeug-Endpunkte: Die Option as24ci_rest_api_enabled muss auf 1 gesetzt sein. Bis dahin sind die Routen nicht registriert und jede Anfrage gibt ein 404 von WordPress zurück.
• Für den Cron-Import-Endpunkt: Ein Cron-Token muss im Admin-Tab Import & Limits generiert werden.

Endpunkt-Referenz

GET /as24ci/v1/vehicles

Gibt eine paginierte, filterbare Liste importierter Fahrzeuge zurück, deren CPT-Beitragsstatus publish ist.

• Authentifizierung: Keine (öffentlich). Route wird nur registriert, wenn as24ci_rest_api_enabled gleich 1 ist.
• Query-Parameter:
• page – Ganzzahl ≥ 1. Standard 1.
• per_page – Ganzzahl zwischen 1 und 100. Standard 10.
• make, model – exakte Übereinstimmung mit den entsprechenden Meta-Keys.
• fuel_type – LIKE-Übereinstimmung mit dem gemappten Kraftstoffart-Meta-Key.
• year_min, year_max – numerischer Bereich für _as24ci_year.
• price_min, price_max – numerischer Bereich für _as24ci_price.
• orderby – einer von date, price, mileage, title. Standard date.
• order – asc oder desc (Groß-/Kleinschreibung egal). Standard desc.
• Antwort-Struktur: ``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 } ``
• Hinweise: Das Feld image ist die mittelgroße WordPress-Größe des Beitragsbildes (leerer String, wenn kein Vorschaubild existiert). Das Feld currency fällt auf den Wert der Option as24ci_default_currency zurück, wenn keine fahrzeugspezifische Währung gespeichert ist.

GET /as24ci/v1/vehicles/<id>

Gibt vollständige Details für ein einzelnes Fahrzeug zurück.

• Authentifizierung: Keine (öffentlich). Gleiche Einschränkung wie beim Listen-Endpunkt.
• Pfad-Parameter: id – positive Ganzzahl. Validiert und konvertiert zu absint.
• Antwort: Alle Felder aus der Listen-Antwort plus:
• description – verwendet den WordPress-Auszug, falls vorhanden, andernfalls den gekürzten Beitragsinhalt (ca. 55 Wörter).
• images – Array von Anhang-URLs in der Größe large, das manuelle Galeriebilder (_as24ci_manual_image_ids) und importierte Bilder (_as24ci_image_ids) kombiniert; fällt auf das Beitragsbild zurück, wenn beide leer sind.
• equipment_standard, equipment_optional – Arrays von Strings.
• seller – Anzeigename des Autohauses.
• Fehler:
• 404 (as24ci_vehicle_not_found), wenn der Beitrag nicht existiert, nicht der CPT as24ci_car ist oder nicht veröffentlicht ist.

POST /as24ci/v1/favorites

Wird von der Frontend-Favoritenseite verwendet, um Fahrzeug-Zusammenfassungsdaten für die IDs abzurufen, die der Besucher im lokalen Browserspeicher hinterlegt hat.

• Authentifizierung: Keine (öffentlich). Immer registriert.
• Body: JSON-Objekt mit ids, einem Array von Beitrags-IDs. Validiert als Array; bereinigt zu einer eindeutigen Liste positiver Ganzzahlen. Bis zu 50 IDs werden pro Aufruf verarbeitet.
• Antwort: { "vehicles": [ ... ] }.
• Hinweise: Der Endpunkt liest nur veröffentlichte Fahrzeuge. Beiträge, auf die der Besucher keinen Zugriff mehr hat (gelöscht, Entwurf, falscher Beitragstyp), werden stillschweigend weggelassen.

POST /as24ci/v1/analytics/track

Empfängt Ereignisse für Detailansicht, Archivansicht, Vergleichsansicht, Favoritenansicht, Filtersuche, Kontakt-Öffnung und Lead-Absendung vom Analyse-Tracking-Pixel.

• Authentifizierung: Keine (öffentlich). Immer registriert.
• Body-Parameter:
• post_id – Ganzzahl ≥ 0. Standard 0.
• event_type – muss einer der erlaubten Ereignisnamen sein: view, view_archive, view_compare, view_favorites, filter_search, contact_open, lead_sent.
• extra_data – optionaler bereinigter String. Für filter_search muss der String ein JSON-Objekt sein, das die aktiven Filter-Schlüssel/Wert-Paare enthält; der Server wendet dieselbe Minimierungslogik an, die auch beim direkten PHP-Tracking vor dem Speichern genutzt wird.
• Antwort: { "tracked": true } bei Erfolg, { "tracked": false } mit HTTP 400, wenn das Ereignis einen Fahrzeugbeitrag erfordert, der nicht existiert oder nicht veröffentlicht ist.
• Hinweise: Dieser Endpunkt ist absichtlich tolerant gestaltet, damit anonyme Besucher Analyse-Ereignisse senden können. Verlassen Sie sich nicht darauf für verbindliche Geschäftsdaten; siehe Analyse-Tracking für Hinweise zu Aufbewahrung und Datenschutz.

GET /as24ci/v1/cron-import

Token-geschützter Endpunkt, der die gemeinsame Import-Routine ausführt. Er delegiert an dieselbe Methode Scheduler::run_import(), die auch vom WP-Cron-Hook und der Admin-Schaltfläche Jetzt ausführen verwendet wird.

• Authentifizierung: Bearer-Token. Stellen Sie das Token entweder über den HTTP-Header Authorization: Bearer <token> bereit (bevorzugt – hält das Token aus den Zugriffsprotokollen fern) oder über den Query-Parameter ?token=<token>.
• Token-Speicherung: Gespeichert in der Option as24ci_cron_token. Generieren oder rotieren Sie es unter Import & Limits im Plugin-Adminbereich.
• Antworten:
• 403, wenn kein Token konfiguriert ist oder das übermittelte Token nicht übereinstimmt.
• 200 mit { "success": true, "message": "...", "counts": { ... } } bei einem erfolgreichen Durchlauf.
• 429 mit success: false, wenn bereits ein anderer Import läuft und der Runner den Start eines zweiten Durchlaufs abgelehnt hat.
• 500, wenn der Runner eine Exception ausgelöst hat.
• Nebeneffekt: Eine erfolgreiche Authentifizierung aktualisiert die Option as24ci_last_external_cron_run, die vom Tab System & Hilfe verwendet wird, um zu bestätigen, dass der externe Cron die Website erreicht.

POST /as24ci/v1/license-refresh-signal

Reiner Signal-Endpunkt, den die ADP Car Market Hub-API-Plattform nach einer Lizenz- oder Feature-Rechte-Änderung aufruft, damit das Plugin seinen maßgeblichen Status sofort neu abruft. Gehört zu AS24CI\License_Refresh_Signal und ist bedingungslos registriert (wie /cron-import), unabhängig von as24ci_rest_api_enabled.

• Authentifizierung: Wird innerhalb des Callbacks über ein rein signalbasiertes Vertrauensmodell abgewickelt. Nichts aus dem Request-Body wird als Daten vertraut; die Anfrage löst nur License_Manager::refresh() aus. Der Handler erzwingt der Reihe nach: POST + JSON-Content-Type; eine übereinstimmende product_key (gegen License_Client::PRODUCT_KEY); eine übereinstimmende installation_uid, wenn beide Seiten eine haben; eine konfigurierte lokale Lizenz; ein bereitgestelltes Aktualisierungssignal-Geheimnis pro Installation; einen frischen Zeitstempel-Header und eine ungenutzte Nonce (Replay-Schutz, 5-Minuten-Fenster); und eine HMAC-SHA256-Signatur über den Zeitstempel + Raw-Body.
• Rate Limiting: Wiederholte Signale innerhalb eines 30-Sekunden-Fensters werden akzeptiert-aber-nicht-aktualisiert und mit 429 beantwortet, damit eine Signalflut niemals die API-Plattform überlasten kann.
• Antworten: 200 bei einer ausgelösten Aktualisierung; 4xx/503 für die oben genannten Validierungsfehler (403 Produkt-/Installationskonflikt, 409 nicht lizenziert / wiederholte Nonce, 401 fehlerhafter Zeitstempel/Signatur, 503, wenn kein Signal-Geheimnis bereitgestellt ist).

Betriebshinweise

• Die öffentlichen Fahrzeug-Endpunkte führen standardmäßige WP_Query-Aufrufe aus und berücksichtigen das normale WordPress-Objekt-Caching. Wiederholte identische Anfragen profitieren von den Beitrags- und Beitrags-Meta-Caches.
• Numerische Filter (year_min/year_max, price_min/price_max) werden zu einer meta_query hinzugefügt. Stellen Sie bei großen Katalogen sicher, dass die zugrunde liegenden Meta-Keys auf Datenbankebene indiziert sind, wenn Sie mit hohem Traffic rechnen. Überprüfen Sie die genaue Indizierungsstrategie in der aktuellen Plugin-Version vor der Veröffentlichung.
• Der Listen-Endpunkt wendet update_postmeta_cache() für die zurückgegebenen Beiträge an, um die Antwortzeiten vorhersehbar zu halten.
• Der Favoriten-Endpunkt begrenzt jede Anfrage hart auf 50 IDs, um Missbrauch zu verhindern und die Antwort-Payloads in einem angemessenen Rahmen zu halten.
• Der Cron-Import-Endpunkt setzt nocache_headers(), damit Caching-Proxys geplante Durchläufe nicht beeinträchtigen.
• Der Token-Vergleich verwendet hash_equals(), um Timing-Angriffe abzumildern. Bevorzugen Sie dennoch den Header Authorization: Bearer, um ein Durchsickern des Tokens über Referrer-Header, den Browserverlauf oder Webserver-Zugriffsprotokolle zu vermeiden.

Konfigurationsreferenz

Die vollständige Liste der Plugin-Optionen finden Sie unter Speicherung von Optionen und Einstellungen.

Fehlerbehebung

• /vehicles gibt 404 zurück – die öffentliche API ist deaktiviert. Setzen Sie as24ci_rest_api_enabled auf '1' in Import & Limits (oder über WP-CLI / update_option).
• /cron-import gibt 403 zurück – entweder ist noch kein Token konfiguriert oder der übermittelte Wert stimmt nicht überein. Generieren Sie ein neues Token im Adminbereich und versuchen Sie es erneut.
• /cron-import gibt 429 zurück – ein anderer Import läuft bereits und eine Sperre verhindert einen zweiten gleichzeitigen Durchlauf. Warten Sie, bis der aktuelle Durchlauf beendet ist; siehe Cron-Ereignisse und Scheduler für die Sperr-TTL.
• Leeres vehicles-Array auf dem Listen-Endpunkt ohne Filter – es sind keine Fahrzeuge veröffentlicht oder der Katalog wurde noch nicht importiert. Überprüfen Sie Import & Limits und die Import-Protokolle.
• Unerwartetes HTTP 400 auf /analytics/track – das Ereignis erfordert einen veröffentlichten Fahrzeugbeitrag, aber post_id verweist auf einen Entwurf, einen gelöschten oder einen Nicht-Fahrzeug-Beitrag.

Zugehörige Dokumente

• AJAX-Aktionen
• Webhooks
• Cron-Ereignisse und Scheduler
• Speicherung von Optionen und Einstellungen
• Analyse-Tracking
• Sicherheit und Berechtigungen