Documentación · Documentación técnica

Almacenamiento y procesamiento de leads

Este documento describe cómo el plugin ADP Car Market Hub captura los envíos de formularios de contacto y de pruebas de conducción, dónde se almacenan, cómo se gestiona el estado de su flujo de trabajo y qué correos electrónicos automatizados se envían.

Cuándo usar este documento

Lea este documento si necesita:

Comprender el esquema y el ciclo de vida de un lead generado por el formulario de contacto del plugin.
Mapear los datos de los leads a un CRM externo a través de la pantalla de administración de leads o los campos post-meta _as24ci_lead_*.
Diagnosticar notificaciones faltantes o estados de flujo de trabajo bloqueados.
Migrar leads entre entornos.

Para endpoints REST/AJAX entrantes, consulte REST API Endpoints y AJAX Actions. Para notificaciones salientes, consulte Webhooks.

Descripción general

Los leads se almacenan como publicaciones del tipo de contenido personalizado (CPT) as24ci_lead, implementado en AS24CI\Leads_CPT. El CPT está registrado como public => false, show_ui => false y show_in_rest => false, por lo que no está expuesto al frontend ni a la REST API de WordPress. La pestaña de administración Leads proporciona una tabla de lista personalizada para visualización, búsquedas, cambios de estado y eliminación.

Cada envío fluye a través del formulario de contacto (AS24CI\Contact_Form), el cual:

Valida y sanea la entrada del formulario.
Envía el correo electrónico de notificación al concesionario y el correo electrónico de confirmación al cliente (utilizando las plantillas personalizadas configuradas o las predeterminadas integradas).
Llama a Leads_CPT::save_lead() para persistir un nuevo registro de lead.
Registra un evento de analítica lead_sent cuando hay un ID de vehículo presente.

Campos de publicación de leads

Leads_CPT::save_lead() escribe las siguientes claves meta:

Clave meta	Origen	Saneador
`_as24ci_lead_name`	Nombre del formulario	`sanitize_text_field`
`_as24ci_lead_email`	Correo electrónico del formulario	`sanitize_email`
`_as24ci_lead_phone`	Teléfono del formulario	`sanitize_text_field`
`_as24ci_lead_message`	Mensaje del formulario	`wp_kses_post`
`_as24ci_lead_vehicle_id`	ID de publicación del vehículo	`absint`
`_as24ci_lead_vehicle_title`	Título del vehículo en el momento del envío	`sanitize_text_field`
`_as24ci_lead_vehicle_listing_id`	Identificador del anuncio de origen	`sanitize_text_field`
`_as24ci_lead_vehicle_url`	Enlace permanente del vehículo	`sanitize_url`
`_as24ci_lead_source_url`	Referer HTTP o URL del vehículo	`sanitize_url`
`_as24ci_lead_date`	Marca de tiempo UTC del envío (`Y-m-d H:i:s`)	—
`_as24ci_lead_email_sent`	`1` cuando se enviaron ambos correos, de lo contrario `0`	—
`_as24ci_lead_status`	Estado del flujo de trabajo (por defecto `new`)	—
`_as24ci_lead_appointment_date`	Fecha de la prueba de conducción (`Y-m-d` o `Y-m-d H:i`)	Comprobación de formato estricta
`_as24ci_lead_is_test_drive`	`1` cuando el formulario es una solicitud de prueba de conducción	—

El post_title se establece con el nombre de contacto y post_status es publish.

Flujo de trabajo de estados

Leads_CPT define cuatro estados de flujo de trabajo:

Constante	Slug	Etiqueta por defecto
`STATUS_NEW`	`new`	Nuevo
`STATUS_CONTACTED`	`contacted`	Contactado
`STATUS_CLOSED`	`closed`	Cerrado
`STATUS_SPAM`	`spam`	Spam

get_lead_status() devuelve el estado almacenado, aplicando por defecto new cuando el meta no existe o no se reconoce. update_lead_status() rechaza valores desconocidos.

La acción de cambio de estado en la administración se expone a través del controlador AJAX as24ci_update_lead_status (capacidad: manage_as24_imports, nonce: as24ci_update_lead_status).

Instrucciones paso a paso

Para revisar y procesar un lead:

Abra la pestaña de administración Leads.
Utilice el cuadro de búsqueda para filtrar por nombre, correo electrónico, ID de anuncio o título del vehículo (coincidencia de LIKE en el lado del servidor contra las claves meta correspondientes).
Utilice el menú desplegable de estado para filtrar por new, contacted, closed o spam.
Abra un lead para ver sus detalles y luego cambie el estado a medida que progrese el flujo de trabajo.
Utilice la acción de eliminar para borrar un lead de forma permanente. El registro se elimina a través de wp_delete_post( $id, true ); no hay paso por la papelera para as24ci_lead.

Comportamiento del correo electrónico

Se envían dos correos electrónicos por cada envío:

Notificación al concesionario — se envía a la dirección configurada en as24ci_lead_recipient_email. Utiliza HTML e incluye los detalles del vehículo, del cliente y del mensaje. Se puede configurar una plantilla personalizada a través de los ajustes de administración de Leads.
Confirmación al cliente — se envía a la dirección de correo electrónico del visitante. Dispone de plantillas independientes para consultas estándar y reservas de pruebas de conducción, y admite una plantilla personalizada almacenada en la opción as24ci_lead_email_template_customer.

Ambos correos electrónicos utilizan wp_mail(). El meta _as24ci_lead_email_sent registra si ambos mensajes se enviaron correctamente (los valores booleanos de retorno de wp_mail() se combinan mediante un operador AND).

Referencia de configuración

Clave de opción	Propósito
`as24ci_lead_recipient_email`	Dirección del destinatario para el correo electrónico de notificación al concesionario.
`as24ci_lead_email_template_customer`	Plantilla HTML personalizada opcional para la confirmación al cliente.

Es posible que se expongan opciones de plantilla adicionales para el correo electrónico del concesionario en la pestaña de administración Leads. Verifique la lista exacta con la versión actual del plugin antes de publicar textos de cara al cliente.

Notas operativas

El CPT no se expone intencionadamente en la REST API ni en el editor de bloques; trate la pestaña de administración de WordPress Leads como la única interfaz de usuario.
wp_count_posts( 'as24ci_lead' ) es utilizado por el widget del dashboard para mostrar el recuento total de leads.
Los leads se escriben desde la misma solicitud HTTP que procesó el envío del formulario. Un fallo en wp_mail() no impide que el lead se almacene; la marca _as24ci_lead_email_sent refleja únicamente el estado del correo electrónico.
El evento de analítica lead_sent solo se registra cuando hay un vehicle_id válido presente en el envío.
Integración de webhooks: un webhook saliente new_lead está conectado internamente en la acción as24ci_lead_saved. Verifique en la versión actual del plugin si esta acción se despacha en el momento de guardar el lead antes de confiar en ella para integraciones en producción.

Resolución de problemas

El lead se guarda pero no llegan correos electrónicos — compruebe el meta _as24ci_lead_email_sent. Si es 0, wp_mail() falló. Verifique la configuración de SMTP/servidor de correo y la dirección del destinatario.
El lead de prueba de conducción no tiene fecha de cita — la cita solo se almacena cuando la entrada coincide con Y-m-d H:i o Y-m-d y representa una fecha real del calendario. Las fechas mal escritas se descartan silenciosamente para mantener la coherencia del registro del lead.
Los cambios de estado se revierten al recargar — confirme que la actualización de estado por AJAX devolvió success. Un 403 indica que el usuario carece de manage_as24_imports; un 400/Invalid parameters significa que el ID del lead o el estado faltaba o no era válido.
La búsqueda no devuelve resultados a pesar de haber contenido coincidente — las búsquedas utilizan LIKE contra cuatro claves meta específicas. Los términos de búsqueda que solo aparecen en el cuerpo del mensaje no se indexan.
Los totales de leads en el widget del dashboard parecen incorrectos — el recuento se basa únicamente en el estado publish. Los leads marcados como spam siguen siendo publish pero con _as24ci_lead_status = spam.