Dokumentation · Technische Dokumentation

Lead-Speicherung und -Verarbeitung

Dieses Dokument beschreibt, wie das ADP Car Market Hub-Plugin Kontaktformular- und Probefahrt-Anfragen erfasst, wo diese gespeichert werden, wie ihr Workflow-Status verwaltet wird und welche automatisierten E-Mails gesendet werden.

Wann Sie dieses Dokument verwenden sollten

Lesen Sie dieses Dokument, wenn Sie Folgendes tun müssen:

Das Schema und den Lebenszyklus eines Leads verstehen, der durch das Kontaktformular des Plugins generiert wurde.
Lead-Daten über die Leads-Admin-Oberfläche oder die _as24ci_lead_*-Post-Meta-Felder an ein externes CRM übertragen.
Fehlende Benachrichtigungen oder blockierte Workflow-Status diagnostizieren.
Leads zwischen Umgebungen migrieren.

Für eingehende REST/AJAX-Endpunkte siehe REST API Endpoints und AJAX Actions. Für ausgehende Benachrichtigungen siehe Webhooks.

Übersicht

Leads werden als Beiträge des Custom Post Type as24ci_lead gespeichert, der in AS24CI\Leads_CPT implementiert ist. Der CPT ist als public => false, show_ui => false und show_in_rest => false registriert, sodass er nicht im Frontend oder in der WordPress-REST-API offengelegt wird. Der Admin-Tab Leads bietet eine benutzerdefinierte Listenansicht zum Anzeigen, Suchen, Ändern des Status und Löschen.

Jede Anfrage läuft über das Kontaktformular (AS24CI\Contact_Form), welches:

Die Formulareingabe validiert und bereinigt.
Die Benachrichtigungs-E-Mail an die Garage und die Bestätigungs-E-Mail an den Kunden sendet (entweder unter Verwendung der konfigurierten benutzerdefinierten Vorlagen oder der integrierten Standardeinstellungen).
Leads_CPT::save_lead() aufruft, um einen neuen Lead-Datensatz dauerhaft zu speichern.
Ein lead_sent-Analytics-Event aufzeichnet, wenn eine Fahrzeug-ID vorhanden ist.

Lead-Beitragsfelder

Leads_CPT::save_lead() schreibt die folgenden Meta-Keys:

Meta-Key	Quelle	Bereinigung
`_as24ci_lead_name`	Formular Name	`sanitize_text_field`
`_as24ci_lead_email`	Formular E-Mail	`sanitize_email`
`_as24ci_lead_phone`	Formular Telefon	`sanitize_text_field`
`_as24ci_lead_message`	Formular Nachricht	`wp_kses_post`
`_as24ci_lead_vehicle_id`	Fahrzeug-Post-ID	`absint`
`_as24ci_lead_vehicle_title`	Fahrzeugtitel zum Zeitpunkt der Anfrage	`sanitize_text_field`
`_as24ci_lead_vehicle_listing_id`	Quell-Listing-ID	`sanitize_text_field`
`_as24ci_lead_vehicle_url`	Fahrzeug-Permalink	`sanitize_url`
`_as24ci_lead_source_url`	HTTP-Referer oder Fahrzeug-URL	`sanitize_url`
`_as24ci_lead_date`	UTC-Zeitstempel der Anfrage (`Y-m-d H:i:s`)	—
`_as24ci_lead_email_sent`	`1`, wenn beide E-Mails versendet wurden, andernfalls `0`	—
`_as24ci_lead_status`	Workflow-Status (Standard ist `new`)	—
`_as24ci_lead_appointment_date`	Probefahrt-Datum (`Y-m-d` oder `Y-m-d H:i`)	Strikte Formatprüfung
`_as24ci_lead_is_test_drive`	`1`, wenn das Formular eine Probefahrt-Anfrage ist	—

Der post_title wird auf den Kontaktnamen gesetzt und post_status ist publish.

Status-Workflow

Leads_CPT definiert vier Workflow-Status:

Konstante	Slug	Standard-Label
`STATUS_NEW`	`new`	Neu
`STATUS_CONTACTED`	`contacted`	Kontaktiert
`STATUS_CLOSED`	`closed`	Geschlossen
`STATUS_SPAM`	`spam`	Spam

get_lead_status() gibt den gespeicherten Status zurück und fällt auf new zurück, wenn die Meta-Daten fehlen oder nicht erkannt werden. update_lead_status() weist unbekannte Werte zurück.

Die Statusänderungs-Aktion im Admin-Bereich wird über den AJAX-Handler as24ci_update_lead_status bereitgestellt (Berechtigung: manage_as24_imports, Nonce: as24ci_update_lead_status).

Schritt-für-Schritt-Anleitung

So überprüfen und verarbeiten Sie einen Lead:

Öffnen Sie den Admin-Tab Leads.
Verwenden Sie das Suchfeld, um nach Name, E-Mail, Listing ID oder Fahrzeugtitel zu filtern (serverseitiger LIKE-Abgleich mit den entsprechenden Meta-Keys).
Verwenden Sie das Status-Dropdown, um nach new, contacted, closed oder spam zu filtern.
Öffnen Sie einen Lead, um dessen Details anzuzeigen, und ändern Sie den Status im Verlauf des Workflows.
Verwenden Sie die Löschaktion, um einen Lead dauerhaft zu entfernen. Der Datensatz wird über wp_delete_post( $id, true ) gelöscht; es gibt keinen Papierkorb-Schritt für as24ci_lead.

E-Mail-Verhalten

Pro Anfrage werden zwei E-Mails gesendet:

Benachrichtigung der Garage — gesendet an die in as24ci_lead_recipient_email konfigurierte Adresse. Verwendet HTML und enthält die Fahrzeug-, Kunden- und Nachrichtendetails. Eine benutzerdefinierte Vorlage kann über die Leads-Admin-Einstellungen konfiguriert werden.
Kundenbestätigung — gesendet an die E-Mail-Adresse des Besuchers. Verfügt über separate Vorlagen für Standardanfragen und Probefahrtbuchungen und unterstützt eine benutzerdefinierte Vorlage, die in der Option as24ci_lead_email_template_customer gespeichert ist.

Beide E-Mails verwenden wp_mail(). Die Meta-Daten in _as24ci_lead_email_sent zeichnen auf, ob beide Nachrichten erfolgreich versendet wurden (die booleschen Rückgabewerte von wp_mail() werden mit UND verknüpft).

Konfigurationsreferenz

Options-Key	Zweck
`as24ci_lead_recipient_email`	Empfängeradresse für die Benachrichtigungs-E-Mail der Garage.
`as24ci_lead_email_template_customer`	Optionale benutzerdefinierte HTML-Vorlage für die Kundenbestätigung.

Zusätzliche Vorlagenoptionen für die E-Mail auf Garagenseite können im Admin-Tab Leads bereitgestellt werden. Überprüfen Sie die genaue Liste anhand der aktuellen Plugin-Version, bevor Sie kundenorientierte Texte veröffentlichen.

Betriebliche Hinweise

Der CPT wird absichtlich nicht in der REST-API oder im Block-Editor offengelegt; behandeln Sie den WP-Admin-Tab Leads als die einzige Benutzeroberfläche.
wp_count_posts( 'as24ci_lead' ) wird vom Dashboard-Widget verwendet, um die Gesamtzahl der Leads anzuzeigen.
Leads werden aus demselben HTTP-Request geschrieben, der die Formularübermittlung verarbeitet hat. Ein fehlgeschlagener wp_mail() verhindert nicht das Speichern des Leads; das Flag _as24ci_lead_email_sent spiegelt nur den E-Mail-Status wider.
Das Analytics-Event lead_sent wird nur aufgezeichnet, wenn eine gültige vehicle_id in der Anfrage vorhanden ist.
Webhook-Integration: Ein ausgehender new_lead-Webhook ist intern mit der Aktion as24ci_lead_saved verknüpft. Überprüfen Sie in der aktuellen Plugin-Version, ob diese Aktion zum Zeitpunkt der Lead-Speicherung ausgelöst wird, bevor Sie sich bei Produktionsintegrationen darauf verlassen.

Fehlerbehebung

Lead wird gespeichert, aber es kommen keine E-Mails an — Überprüfen Sie die Meta-Daten in _as24ci_lead_email_sent. Wenn diese 0 sind, ist wp_mail() fehlgeschlagen. Überprüfen Sie die SMTP-/Mailer-Konfiguration und die Empfängeradresse.
Probefahrt-Lead hat kein Termindatum — Der Termin wird nur gespeichert, wenn die Eingabe mit Y-m-d H:i oder Y-m-d übereinstimmt und ein reales Kalenderdatum darstellt. Falsch eingegebene Daten werden stillschweigend verworfen, um den Lead-Datensatz konsistent zu halten.
Statusänderungen werden beim Neuladen zurückgesetzt — Bestätigen Sie, dass das AJAX-Status-Update success zurückgegeben hat. Ein 403 weist darauf hin, dass dem Benutzer die Berechtigung manage_as24_imports fehlt; ein 400/Invalid parameters bedeutet, dass die Lead-ID oder der Status fehlte oder ungültig war.
Die Suche liefert trotz passendem Inhalt keine Ergebnisse — Suchen verwenden LIKE gegen vier spezifische Meta-Keys. Suchbegriffe, die nur im Nachrichtentext vorkommen, werden nicht indexiert.
Die Lead-Gesamtzahlen im Dashboard-Widget sehen falsch aus — Die Zählung basiert nur auf dem Status publish. Als Spam markierte Leads bleiben publish, jedoch mit _as24ci_lead_status = spam.