Documentazione · Documentazione tecnica

Archiviazione e gestione dei lead

Questo documento descrive come il plugin ADP Car Market Hub acquisisce i dati inviati tramite i moduli di contatto e di richiesta di test drive, dove vengono archiviati, come viene gestito il loro stato nel flusso di lavoro e quali email automatiche vengono inviate.

Quando utilizzare questo documento

Leggi questo documento se hai bisogno di:

Comprendere lo schema e il ciclo di vita di un lead generato dal modulo di contatto del plugin.
Mappare i dati dei lead verso un CRM esterno tramite la schermata di amministrazione dei lead o i campi post-meta _as24ci_lead_*.
Diagnosticare notifiche mancanti o stati del flusso di lavoro bloccati.
Migrare i lead tra ambienti diversi.

Per gli endpoint REST/AJAX in entrata, consulta REST API Endpoints e AJAX Actions. Per le notifiche in uscita, consulta Webhooks.

Panoramica

I lead vengono archiviati come post del custom post type as24ci_lead, implementato in AS24CI\Leads_CPT. Il CPT è registrato come public => false, show_ui => false e show_in_rest => false, pertanto non è esposto nel front-end o nell'API REST di WordPress. La scheda Leads dell'amministratore fornisce una tabella personalizzata per la visualizzazione, la ricerca, la modifica dello stato e l'eliminazione.

Ogni invio passa attraverso il modulo di contatto (AS24CI\Contact_Form), che:

Valida e bonifica i dati inseriti nel modulo.
Invia l'email di notifica al concessionario e l'email di conferma al cliente (utilizzando i template personalizzati configurati o quelli predefiniti integrati).
Richiama Leads_CPT::save_lead() per salvare un nuovo record di lead.
Registra un evento analitico lead_sent quando è presente l'ID di un veicolo.

Campi post dei lead

Leads_CPT::save_lead() scrive le seguenti chiavi meta:

Chiave meta	Origine	Funzione di bonifica
`_as24ci_lead_name`	Campo modulo Nome	`sanitize_text_field`
`_as24ci_lead_email`	Campo modulo Email	`sanitize_email`
`_as24ci_lead_phone`	Campo modulo Telefono	`sanitize_text_field`
`_as24ci_lead_message`	Campo modulo Messaggio	`wp_kses_post`
`_as24ci_lead_vehicle_id`	ID del post del veicolo	`absint`
`_as24ci_lead_vehicle_title`	Titolo del veicolo al momento dell'invio	`sanitize_text_field`
`_as24ci_lead_vehicle_listing_id`	Identificativo dell'annuncio di origine	`sanitize_text_field`
`_as24ci_lead_vehicle_url`	Permalink del veicolo	`sanitize_url`
`_as24ci_lead_source_url`	Referer HTTP o URL del veicolo	`sanitize_url`
`_as24ci_lead_date`	Timestamp UTC dell'invio (`Y-m-d H:i:s`)	—
`_as24ci_lead_email_sent`	`1` quando entrambe le email sono state inviate, altrimenti `0`	—
`_as24ci_lead_status`	Stato del flusso di lavoro (predefinito su `new`)	—
`_as24ci_lead_appointment_date`	Data del test drive (`Y-m-d` o `Y-m-d H:i`)	Controllo rigoroso del formato
`_as24ci_lead_is_test_drive`	`1` quando il modulo è una richiesta di test drive	—

Il campo post_title è impostato sul nome del contatto e post_status è publish.

Flusso di lavoro degli stati

Leads_CPT definisce quattro stati per il flusso di lavoro:

Costante	Slug	Etichetta predefinita
`STATUS_NEW`	`new`	Nuovo
`STATUS_CONTACTED`	`contacted`	Contattato
`STATUS_CLOSED`	`closed`	Chiuso
`STATUS_SPAM`	`spam`	Spam

get_lead_status() restituisce lo stato archiviato, impostando come predefinito new se il meta è mancante o non riconosciuto. update_lead_status() rifiuta i valori sconosciuti.

L'azione di modifica dello stato lato amministratore è esposta tramite l'handler AJAX as24ci_update_lead_status (capability: manage_as24_imports, nonce: as24ci_update_lead_status).

Istruzioni passo dopo passo

Per esaminare e gestire un lead:

Apri la scheda di amministrazione Leads.
Usa la casella di ricerca per filtrare per nome, email, ID dell'annuncio o titolo del veicolo (corrispondenza lato server LIKE rispetto alle chiavi meta corrispondenti).
Usa il menu a discesa dello stato per filtrare per new, contacted, closed o spam.
Apri un lead per visualizzarne i dettagli, quindi modifica lo stato man mano che il flusso di lavoro avanza.
Usa l'azione di eliminazione per rimuovere definitivamente un lead. Il record viene rimosso tramite wp_delete_post( $id, true ); non è previsto un passaggio nel cestino per as24ci_lead.

Comportamento delle email

Vengono inviate due email per ogni invio di modulo:

Notifica al concessionario — inviata all'indirizzo configurato in as24ci_lead_recipient_email. Utilizza il formato HTML e include i dettagli del veicolo, del cliente e del messaggio. È possibile configurare un template personalizzato tramite le impostazioni di amministrazione dei Leads.
Conferma al cliente — inviata all'indirizzo email del visitatore. Dispone di template separati per le richieste standard e per le prenotazioni di test drive, e supporta un template personalizzato memorizzato nell'opzione as24ci_lead_email_template_customer.

Entrambe le email utilizzano wp_mail(). Il meta _as24ci_lead_email_sent registra se entrambi i messaggi sono stati inviati correttamente (i valori booleani restituiti da wp_mail() sono combinati con l'operatore AND).

Riferimento di configurazione

Chiave opzione	Scopo
`as24ci_lead_recipient_email`	Indirizzo del destinatario per l'email di notifica al concessionario.
`as24ci_lead_email_template_customer`	Template HTML personalizzato opzionale per la conferma al cliente.

Ulteriori opzioni di template per l'email lato concessionario potrebbero essere esposte nella scheda di amministrazione Leads. Verifica l'elenco esatto rispetto alla versione corrente del plugin prima di pubblicare testi visibili ai clienti.

Note operative

Il CPT non è intenzionalmente esposto nell'API REST o nell'editor a blocchi; considera la scheda Leads dell'amministratore di WordPress come l'unica interfaccia utente.
wp_count_posts( 'as24ci_lead' ) viene utilizzato dal widget della bacheca per visualizzare il conteggio totale dei lead.
I lead vengono scritti a partire dalla stessa richiesta HTTP che ha elaborato l'invio del modulo. Un errore in wp_mail() non impedisce il salvataggio del lead; il flag _as24ci_lead_email_sent riflette solo lo stato dell'email.
L'evento analitico lead_sent viene registrato solo quando nell'invio è presente un vehicle_id valido.
Integrazione webhook: un webhook new_lead in uscita è collegato internamente sull'azione as24ci_lead_saved. Verifica nella versione corrente del plugin se questa azione viene inviata al momento del salvataggio del lead prima di fare affidamento su di essa per le integrazioni in produzione.

Risoluzione dei problemi

Il lead viene salvato ma non arriva alcuna email — controlla il meta _as24ci_lead_email_sent. Se è 0, significa che wp_mail() ha riscontrato un errore. Verifica la configurazione di SMTP/mailer e l'indirizzo del destinatario.
Il lead del test drive non ha una data di appuntamento — l'appuntamento viene memorizzato solo quando l'input corrisponde a Y-m-d H:i o Y-m-d e rappresenta una data reale del calendario. Le date digitate in modo errato vengono scartate silenziosamente per mantenere coerente il record del lead.
Le modifiche di stato vengono ripristinate al ricaricamento della pagina — conferma che l'aggiornamento dello stato AJAX abbia restituito success. Un valore 403 indica che l'utente non dispone di manage_as24_imports; un valore 400/Invalid parameters significa che l'ID del lead o lo stato era mancante o non valido.
La ricerca non restituisce risultati nonostante la presenza di contenuti corrispondenti — le ricerche utilizzano LIKE rispetto a quattro chiavi meta specifiche. I termini di ricerca che compaiono solo nel corpo del messaggio non vengono indicizzati.
I totali dei lead nel widget della bacheca sembrano errati — il conteggio si basa solo sullo stato publish. I lead contrassegnati come spam rimangono publish ma con _as24ci_lead_status = spam.