REST-Endpoint-Referenz

Dieser Anhang listet die REST-API-Routen auf, die vom ADP Car Market Hub-Plugin unter dem Namespace as24ci/v1 registriert wurden.

Wann Sie dieses Dokument verwenden sollten

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

Übersicht

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

Die Endpoints lassen sich in fünf Gruppen einteilen:

1. Öffentliche Fahrzeugdaten (/vehicles, /vehicles/{id}) – standardmässig deaktiviert; gesteuert durch as24ci_rest_api_enabled.
2. Favoriten-Helfer (/favorites) – wird von der Favoritenseite im Frontend 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 Platform verwendet, um die Website zur erneuten Validierung ihrer Lizenz aufzufordern.

Endpoint-Übersicht

GET /as24ci/v1/vehicles

Paginierte, filterbare Liste der importierten Fahrzeuge, deren Post-Status publish ist.

Query-Parameter:

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 mittelgrosse (medium-large) Grösse des Beitragsbildes (leerer String, wenn keines vorhanden ist). 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.

• Pfad-Parameter: id – positive Ganzzahl; validiert und gecastet durch absint.
• Auth: keine (öffentlich). Gleiche Steuerung wie beim Listen-Endpoint.
• Antwort: alle Felder aus der Listen-Antwort plus description, images (Array von Anhang-URLs in der Grösse 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

Füllt die Favoriten des Besuchers mit aktuellen Fahrzeugdaten für IDs ab, 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 Endpoint, der die gemeinsame Import-Routine ausführt. Delegiert an dieselbe Methode Scheduler::run_import(), die auch vom WP-Cron-Hook und der manuellen Admin-Schaltfläche "Jetzt auslösen" verwendet wird.

• Auth: Bearer-Token. Stellen Sie das Token entweder über den HTTP-Header Authorization: Bearer <token> (bevorzugt – hält das Token aus den Zugriffsprotokollen fern) oder den Query-Parameter ?token=<token> bereit. 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-Administration.
• 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 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 Crons (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-Endpoint, mit dem die API Platform die Website auffordern kann, ihre Lizenz ausserhalb 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 Trust-Modell. Die Authentifizierung wird innerhalb des Callbacks und nicht durch ein permission_callback abgewickelt; 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 geparst werden kann.
• 200, wenn das Signal akzeptiert wird.
• Inhaber: AS24CI\License_Refresh_Signal.

Betriebshinweise

• Die öffentlichen Fahrzeug-Endpoints 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 erweitern eine meta_query. 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 Indizierungsstrategie in der aktuellen Plugin-Version vor der Veröffentlichung.
• Der Listen-Endpoint wendet update_postmeta_cache() auf die zurückgegebenen Beiträge an, um die Antwortzeiten vorhersehbar zu halten.
• Der Favoriten-Endpoint begrenzt jede Anfrage hart auf 50 IDs, um Missbrauch vorzubeugen.
• Der Cron-Import-Endpoint 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 Endpoints weiterhin über ?rest_route= erreichbar.

Fehlerbehebung

• /vehicles gibt 404 zurück. Die öffentliche API ist deaktiviert. Setzen Sie as24ci_rest_api_enabled unter 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 in der Administration 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-Endpoint 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-Logs.
• 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 Endpoints
• REST API For Developers
• Cron Hook Reference
• Webhook Event Reference
• Settings Reference