REST-Endpunkt-Referenz

ADP Car Market Hub

Wann Sie dieses Dokument verwenden sollten

Verwenden Sie diese Referenz, wenn Sie einen Plugin-Endpunkt aufrufen müssen, wenn Sie unerwartete 403/404-Antworten diagnostizieren oder wenn Sie eine Integration dokumentieren. Für die konzeptionelle Beschreibung jedes Endpunkts siehe REST-API-Endpunkte.

Übersicht

Alle vom Plugin registrierten Routen verwenden die WordPress-REST-API und teilen sich den Namespace as24ci/v1. Die vollständige URL eines Endpunkts ist die WordPress-REST-Root gefolgt von der Route, typischerweise https://example.com/wp-json/as24ci/v1/....

Die Endpunkte lassen sich in fünf Gruppen einteilen:

1. Öffentliche Fahrzeugdaten (/vehicles, /vehicles/{id}) – standardmäßig deaktiviert; gesteuert durch as24ci_rest_api_enabled.
2. Favoriten-Helfer (/favorites) – wird von der Frontend-Favoritenseite verwendet.
3. Analytics-Tracking (/analytics/track) – wird vom Frontend-Skript verwendet.
4. Cron-Import-Trigger (/cron-import) – Token-geschützt; wird von externen Schedulern verwendet.
5. Lizenz-Aktualisierungssignal (/license-refresh-signal) – wird von der API-Plattform verwendet, um die Website zur erneuten Validierung ihrer Lizenz aufzufordern.

Endpunkt-Übersicht

GET /as24ci/v1/vehicles

Paginierte, filterbare Liste importierter Fahrzeuge, deren Beitragsstatus publish ist.

Abfrageparameter:

Antwort (Struktur):

{
  "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
}

Das Feld image ist die mittelgroße Version des Beitragsbildes (leerer String, wenn keines vorhanden). Das Feld currency fällt auf as24ci_default_currency zurück, wenn keine fahrzeugspezifische Währung gespeichert ist.

GET /as24ci/v1/vehicles/{id}

Vollständige Details für ein einzelnes Fahrzeug.

• Pfadparameter: id – positive Ganzzahl; validiert und konvertiert durch absint.
• Auth: keine (öffentlich). Gleiche Steuerung wie beim Listen-Endpunkt.
• Antwort: alle Felder aus der Listenantwort plus description, images (Array von Anhang-URLs in der Größe large, das manuelle und importierte Bilder kombiniert und auf das Beitragsbild zurückfällt), equipment_standard, equipment_optional und seller.
• 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

Befüllt die Favoriten des Besuchers mit aktuellen Fahrzeugdaten für IDs, die im Local Storage des Browsers gespeichert sind.

• Auth: keine (öffentlich). Immer registriert.
• Body: JSON-Objekt mit ids – ein Array von Beitrags-IDs. Bereinigt zu einer eindeutigen Liste positiver Ganzzahlen; begrenzt auf maximal 50 IDs pro Anfrage.
• Antwort: { "vehicles": [ ... ] }.
• Hinweise: Es werden nur veröffentlichte Fahrzeuge zurückgegeben. 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 Analytics-Ereignisse vom Frontend-Tracking-Pixel.

• Auth: keine (öffentlich). Immer registriert.
• Body-Parameter:
• post_id – Ganzzahl ≥ 0. Standard 0.
• event_type – einer von view, view_archive, view_compare, view_favorites, filter_search, contact_open, lead_sent.
• extra_data – optionaler bereinigter String. Für filter_search muss dies ein JSON-Objekt sein, das die aktiven Filter-Schlüssel/Wert-Paare enthält.
• Antwort: { "tracked": true } bei Erfolg, oder { "tracked": false } mit HTTP 400, wenn das Ereignis einen Fahrzeugbeitrag erfordert, der nicht existiert oder nicht veröffentlicht ist.
• Hinweise: Absichtlich tolerant gestaltet, damit anonyme Besucher Ereignisse senden können. Verlassen Sie sich nicht darauf für verbindliche Geschäftsdaten.

GET /as24ci/v1/cron-import

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

• Auth: 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 Abfrageparameter ?token=<token>. Der Vergleich verwendet hash_equals(), um Timing-Angriffe zu verhindern.
• Token-Speicherung: 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 Durchlaufs abgelehnt hat.
• 500, wenn der Runner eine Exception ausgelöst hat.
• Nebeneffekt: Eine erfolgreiche Authentifizierung aktualisiert as24ci_last_external_cron_run, was der Tab „System & Hilfe“ verwendet, um zu bestätigen, dass der externe Cron die Website erreicht. Der Aufruf einer beliebigen URL mit ?as24ci_cron=1 aktualisiert diesen Zeitstempel ebenfalls über den Heartbeat-Hook auf init.

Beispiel für den Aufruf eines externen Cron-Jobs (Platzhalter – ersetzen Sie Ihren eigenen Host und ein generiertes 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

Leichtgewichtiger Signal-Endpunkt, über den die API-Plattform die Website auffordern kann, ihre Lizenz außerhalb des regulären Ablaufs (z. B. nach einer Tarifänderung) neu zu validieren. Bedingungslos registriert, damit die Plattform ihn immer erreichen kann; er ist nicht hinter der Option für die öffentliche Fahrzeug-REST-API gesperrt.

• Auth: Signal-only-Vertrauensmodell. Die Authentifizierung wird innerhalb des Callbacks und nicht durch einen permission_callback verarbeitet; die Anfrage muss im JSON-Format vorliegen und wird mit der erwarteten Signalstruktur abgeglichen.
• Body: JSON-Objekt. Sichere, nicht geheime Korrelationsfelder (request_id, event) werden nur zur Nachverfolgung zurückgegeben.
• Antworten:
• 405 method_not_allowed, wenn die Anfrage nicht POST ist.
• 400 invalid_content_type, wenn der Body kein JSON ist, oder 400 invalid_json, wenn der Body nicht analysiert werden kann.
• 200, wenn das Signal akzeptiert wird.
• Eigentümer: AS24CI\License_Refresh_Signal.

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 ergänzen eine meta_query. Stellen Sie bei großen Katalogen sicher, dass die zugrunde liegenden Meta-Schlüssel auf Datenbankebene indiziert sind, wenn Sie mit hohem Datenverkehr rechnen. Überprüfen Sie die Indizierungsstrategie in der aktuellen Plugin-Version vor der Veröffentlichung.
• Der Listen-Endpunkt wendet update_postmeta_cache() auf die zurückgegebenen Beiträge an, um die Antwortzeiten vorhersehbar zu halten.
• Der Favoriten-Endpunkt begrenzt jede Anfrage hart auf maximal 50 IDs, um Missbrauch zu verhindern.
• Der Cron-Import-Endpunkt setzt nocache_headers(), damit Caching-Proxys die geplanten Durchläufe nicht beeinträchtigen.
• Schöne Permalinks werden für pfadbasierte REST-URLs empfohlen. Bei einfachen Permalinks sind die Endpunkte weiterhin über ?rest_route= erreichbar.

Fehlerbehebung

• /vehicles gibt 404 zurück. Die öffentliche API ist deaktiviert. Setzen Sie as24ci_rest_api_enabled in Einstellungen → SEO & Integrationen (oder über WP-CLI / update_option) auf '1'.
• /cron-import gibt 403 zurück. Entweder ist kein Token konfiguriert (as24ci_cron_token ist leer – die Antwortnachricht bestätigt dies) oder das angegebene Token stimmt nicht überein. Generieren Sie ein neues Token im Admin-Bereich 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.
• Leeres vehicles-Array beim Listen-Endpunkt ohne Filter. Es sind keine Fahrzeuge veröffentlicht oder der Katalog wurde noch nicht importiert. Überprüfen Sie den Bildschirm Import & Limits und die Import-Protokolle.
• 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

• REST-API-Endpunkte
• REST-API für Entwickler
• Cron-Hook-Referenz
• Webhook-Ereignis-Referenz
• Einstellungs-Referenz