REST-API-Endpunkte

Dieses Dokument beschreibt die REST-API-Routen, die vom ADP Car Market Hub-Plugin unter dem Namespace as24ci/v1 registriert werden, einschliesslich 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 vom Plugin über HTTP 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üssen.

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 Listing- und Detail-Endpunkte. Standardmässig deaktiviert; müssen von einem Administrator aktiviert werden.
2. Favoriten-Helfer — wird von der Favoritenseite im Frontend verwendet, um Fahrzeugdaten für IDs abzurufen, die der Besucher lokal gespeichert hat.
3. Analytics-Tracking-Pixel — empfängt leichtgewichtige 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 Platform aufruft, damit das Plugin seinen massgeblichen Lizenz- / Funktionsrechte-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).
• Schöne Permalinks für REST-URLs im Pfadstil. 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-Post-Status 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 Kraftstofftyp-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 (Gross-/Kleinschreibung ignorieren). 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 mittelgrosse WordPress-Grösse 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 die vollständigen 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össe 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 der Garage.
• Fehler:
• 404 (as24ci_vehicle_not_found), wenn der Beitrag nicht existiert, nicht die CPT as24ci_car ist oder nicht veröffentlicht ist.

POST /as24ci/v1/favorites

Wird von der Favoritenseite im Frontend verwendet, um Fahrzeug-Zusammenfassungsdaten für die IDs abzurufen, die der Besucher im lokalen Browser-Speicher 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-Versand vom Analytics-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 vor dem Speichern dieselbe Minimierungslogik an wie beim direkten PHP-Tracking.
• 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 Analytics-Ereignisse senden können. Verlassen Sie sich nicht darauf für verbindliche Geschäftsdaten; siehe Analytics Tracking für Hinweise zur Aufbewahrung und zum 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 dem Admin-Button Jetzt auslösen 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 in der Plugin-Verwaltung.
• Antworten:
• 403, wenn kein Token konfiguriert ist oder das angegebene 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 Imports 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 Platform nach einer Lizenz- oder Funktionsrechteänderung aufruft, damit das Plugin seinen massgeblichen 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 reines Signal-Vertrauensmodell abgewickelt. Nichts aus dem Request-Body wird als Daten vertraut; der Request löst nur License_Manager::refresh() aus. Der Handler erzwingt der Reihe nach: POST + JSON-Content-Type; eine passende product_key (gegen License_Client::PRODUCT_KEY); eine passende installation_uid, wenn beide Seiten eine haben; eine konfigurierte lokale Lizenz; ein bereitgestelltes installationsspezifisches Refresh-Signal-Secret; einen frischen Zeitstempel-Header und eine unbenutzte Nonce (Replay-Schutz, 5-Minuten-Fenster); und eine HMAC-SHA256-Signatur über den Zeitstempel + rohen Body.
• Rate Limiting: Wiederholte Signale innerhalb eines 30-Sekunden-Fensters werden akzeptiert-aber-nicht-aktualisiert und mit 429 beantwortet, damit ein Burst niemals die API Platform überlasten kann.
• Antworten: 200 bei einer ausgelösten Aktualisierung; 4xx/503 für die oben genannten Validierungsfehler (403 Produkt-/Installations-Fehlanpassung, 409 nicht lizenziert / wiederholte Nonce, 401 ungültiger Zeitstempel/Signatur, 503, wenn kein Signal-Secret bereitgestellt ist).

Betriebshinweise

• Die öffentlichen Fahrzeug-Endpunkte führen standardmässige 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 grossen 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 zu verhindern. Bevorzugen Sie dennoch den Header Authorization: Bearer, um zu verhindern, dass das Token über Referrer-Header, den Browserverlauf oder Webserver-Zugriffsprotokolle offengelegt wird.

Konfigurations-Referenz

Für die vollständige Liste der Plugin-Optionen siehe 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 angegebene Wert stimmt nicht überein. Generieren Sie ein neues Token in der Verwaltung 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.

Verwandte Dokumente

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