Motor de importación

Este documento describe cómo el plugin ADP Car Market Hub importa listados de vehículos desde la API de AutoScout24 a WordPress. Cubre las responsabilidades de las clases del importador, el flujo por listado, la detección de cambios, la eliminación por sincronización completa y el hook público que se activa después de importar un vehículo.

Cuándo usar este documento

Lea este documento si necesita:

• Entender qué sucede durante una ejecución de importación.
• Diagnosticar por qué un vehículo fue insertado, actualizado, omitido o eliminado.
• Crear una integración personalizada que reaccione a las importaciones a través de la acción as24ci_vehicle_imported.
• Planificar la capacidad o los requisitos de hosting para catálogos grandes.

Para detalles sobre la programación y el cron, consulte Cron Events And Scheduler. Para la gestión de imágenes, consulte Image Importer And Queue.

Descripción general

El motor de importación consta de varias clases que trabajan juntas:

• AS24CI\Client — realiza solicitudes HTTP autenticadas a la API de AutoScout24, gestiona los tokens OAuth (incluyendo la caché transitoria as24ci_access_token) y expone funciones auxiliares para páginas de vista previa y equipamiento por listado.
• AS24CI\Importer — coordina la importación por listado. Decide si insertar, actualizar u omitir y escribe la entrada del vehículo, los postmeta y las referencias de imagen. Es responsable de la detección de cambios.
• AS24CI\Mapper — mapea la carga útil (payload) cruda de AutoScout24 a los campos almacenados en la tabla as24_vehicles a través de AS24CI\Vehicle_Repository. Mantiene claves postmeta compatibles con versiones anteriores.
• AS24CI\Vehicle_Repository — persiste los datos de los campos del vehículo en la tabla dedicada {$wpdb->prefix}as24_vehicles.
• AS24CI\Image_Importer — descarga imágenes, opcionalmente las convierte a WebP y las adjunta a la entrada del vehículo. Consulte Image Importer And Queue.
• AS24CI\Scheduler — envuelve a Importer::import_all_for_seller() en un ejecutor con bloqueo y seguro contra reintentos utilizado por WP-Cron, el endpoint REST de cron y el botón manual "Ejecutar ahora".

La misma instancia de Importer es reutilizada por el Batch-Wizard manual, el ejecutor de cron y el endpoint REST de cron.

Requisitos o prerrequisitos

Antes de ejecutar una importación necesita:

• Credenciales válidas de la API de AutoScout24 configuradas en el plugin (as24ci_base_url, as24ci_token_url, as24ci_client_id, as24ci_client_secret, as24ci_token_audience).
• Uno o más Seller IDs en as24ci_seller_ids (separados por comas).
• Un usuario de WordPress designado como autor predeterminado de las entradas (as24ci_default_post_author); las importaciones recurren al usuario actual cuando no se ha establecido un valor predeterminado.
• Acceso HTTPS saliente que funcione desde el servidor de WordPress a la API de AutoScout24 y a los hosts de imágenes referenciados en la respuesta de la API.
• Tiempo de ejecución de PHP suficiente. El programador eleva el límite de tiempo a 300 segundos a través de set_time_limit(300) para las ejecuciones de cron y REST; algunos hostings pueden anular esto.

Flujo por listado

AS24CI\Importer::upsert_post_from_listing() es la rutina central por listado. El flujo simplificado es:

1. Validar que el listado tenga un id. Omitir en caso contrario.
2. Omitir listados cuyo estado en la API no sea activated o cuyo indicador live esté vacío.
3. Buscar una entrada de vehículo existente por Listing ID (find_post_id_by_listing_id()).
4. Ejecutar la detección de cambios (ver más abajo). Si nada ha cambiado, escribir _as24ci_last_sync y devolver skipped.
5. Construir el título, el extracto y el contenido de la entrada. Si el AI Lock (_as24ci_ai_locked = 'yes') está activo, no sobrescribir el extracto ni el contenido de la entrada.
6. Insertar o actualizar la entrada de WordPress con el estado de entrada y el autor predeterminados configurados.
7. Escribir los postmeta de compatibilidad con versiones anteriores: _as24ci_listing_id, _as24ci_seller_id, _as24ci_last_modified (cuando la API lo suministra) y _as24ci_last_sync.
8. Asegurar que el slug termine con el Listing ID (ensure_slug_has_listing_id()).
9. Mapear la carga útil del listado a través de AS24CI\Mapper::map_listing_to_post() para que los campos tipados se escriban en la tabla as24_vehicles.
10. Obtener el equipamiento a través de Client::get_listing_equipment() y mapearlo a la entrada a través de Mapper::map_equipment_to_post(). Los errores se registran en el log pero no hacen fallar la importación del listado.
11. Importar imágenes (sujeto al interruptor as24ci_import_images y al límite as24ci_max_images). El flujo de imágenes se describe en detalle en Image Importer And Queue.
12. Actualizar _as24ci_content_hash y _as24ci_original_description.
13. Activar la acción as24ci_vehicle_imported con el ID de la entrada, el listado crudo de la API y un booleano $is_update.
14. Devolver una de las cadenas inserted, updated, skipped o error (en caso de fallo de wp_insert_post / wp_update_post).

Detección de cambios

El importador omite los listados que no han cambiado desde la ejecución anterior, utilizando dos comprobaciones en cascada:

• Principal: el campo lastModifiedDate devuelto por la API. Si el postmeta local _as24ci_last_modified coincide con el valor remoto, el listado se trata como no modificado. El importador sigue actualizando _as24ci_last_sync para que la lógica de sincronización completa sepa que el listado existe de forma remota.
• Alternativa: cuando falta lastModifiedDate, el importador calcula un MD5 de la carga útil codificada en JSON y lo compara con el _as24ci_content_hash almacenado.

La detección de cambios de imágenes funciona de forma independiente y se describe en la documentación del importador de imágenes.

AI Lock

Cuando _as24ci_ai_locked es 'yes', el importador conserva los valores existentes de post_content y post_excerpt para que los textos generados por IA sobrevivan a una reimportación. Todos los demás campos, asignaciones de taxonomías, equipamiento e imágenes se siguen actualizando. La descripción original de la API también se conserva por separado en _as24ci_original_description.

Estabilidad del slug

ensure_slug_has_listing_id() actualiza el slug de la entrada para que termine con -<listing_id> siempre que el slug cambie. Esto mantiene las URL estables a lo largo de las reimportaciones y evita redireccionamientos accidentales cuando cambian los títulos.

Operaciones masivas

AS24CI\Importer expone los siguientes métodos de alto nivel:

• get_seller_ids() — devuelve la lista limpia de Seller IDs configurados.
• get_all_preview_listings_for_seller( $seller_id, $max_pages = 20, $page_size = 50 ) — pagina a través de la API y devuelve el conjunto completo de listados activos y publicados para un único vendedor.
• preview_listings_for_seller( $seller_id, $page = 1, $per_page = 50 ) — vista previa paginada utilizada por la interfaz de usuario del asistente (wizard).
• import_selected_listings( $seller_id, $listing_ids, $max_vehicles = 0 ) — importa los IDs de listado proporcionados. Respeta el límite de $max_vehicles; los vehículos omitidos no consumen este límite.
• import_all_for_seller( $seller_id, $max_vehicles = 0 ) — obtiene la lista completa de vista previa para un vendedor y la delega a import_selected_listings(). Devuelve los recuentos más listing_ids (el conjunto completo visto en esta ejecución) y api_active (número de listados activos que devolvió la API).
• full_sync_after_import( array $remote_listing_ids ) — elimina las entradas locales de as24ci_car cuyo _as24ci_listing_id no esté en el conjunto remoto proporcionado. Se omite si el conjunto remoto está vacío como medida de seguridad contra borrados accidentales.
• hard_delete_listing( $listing_id ) — eliminación destructiva manual para un solo listado; pasa por la misma limpieza de Vehicle_Deleter que la eliminación nativa de WordPress.

La versión "All-in-One" del plugin no impone ningún límite de listados; get_free_import_limit() y get_free_slots_left() devuelven PHP_INT_MAX.

Eliminación de vehículos

Cualquier ruta de eliminación permanente fluye a través de AS24CI\Vehicle_Deleter:

• La opción nativa de WordPress "Borrar permanentemente" en la lista de Cars.
• Sincronización completa del importador (full_sync_after_import()).
• Acciones en lote (AS24CI\Bulk_Actions).
• Importer::hard_delete_listing() manual.

El eliminador se ejecuta en before_delete_post / deleted_post y:

• Elimina los archivos adjuntos rastreados en _as24ci_image_ids.
• Elimina la fila correspondiente en {$wpdb->prefix}as24_vehicles.
• Activa la acción as24ci_vehicle_deleted.

Los archivos adjuntos de galerías manuales (_as24ci_manual_image_ids) y otros archivos adjuntos no rastreados por el importador se conservan intencionadamente.

Hooks públicos

El motor de importación activa los siguientes hooks. Verifique las firmas de los hooks en la versión actual del plugin antes de confiar en ellos.

El plugin también lee el filtro as24ci_webp_quality al convertir imágenes; consulte la documentación del importador de imágenes.

Referencia de configuración

Notas operativas

• El importador nunca se interrumpe por un único listado defectuoso. Los errores de wp_insert_post, wp_update_post, Client::get_listing_equipment y del importador de imágenes se registran a través de AS24CI\Logger y se contabilizan, pero no abortan la ejecución.
• La detección de cambios significa que una reimportación completa de un catálogo sin cambios es económica: la mayoría de los listados se omiten y no se vuelven a solicitar las descargas de imágenes.
• El mapeador escribe en la tabla as24_vehicles a través del repositorio, no en wp_postmeta, excepto para el pequeño conjunto de claves de compatibilidad con versiones anteriores documentado en Data Model.
• La sincronización completa es opcional (opt-in). Si as24ci_full_sync está activado, asegúrese de que los Seller IDs configurados cubran todo el catálogo que desea mantener en línea; los vehículos cuyos listados desaparezcan de la API se eliminarán de forma permanente.
• El registro detallado (verbose logging) produce líneas de log minuciosas y crece rápidamente en catálogos grandes. El plugin impone un límite de tamaño de log de 10 MB con rotación; ajuste el registro detallado para equilibrar el diagnóstico con el almacenamiento.

Resolución de problemas

• No se importan vehículos. Confirme las credenciales de la API, que as24ci_seller_ids no esté vacío y que la API devuelva listados con status = activated y live = true. Revise el log del plugin para buscar errores HTTP de AS24CI\Client.
• Los listados permanecen en estado draft. El plugin establece por defecto as24ci_default_post_status en draft para que los administradores puedan revisar los mapeos. Cambie la opción a publish una vez que esté satisfecho, o publique vehículos individuales desde la lista de administración.
• Las reimportaciones repetidas siguen actualizando los mismos vehículos. Verifique que la API suministre un lastModifiedDate estable. Cuando este falta, el hash de contenido alternativo detecta los cambios; el hash cambiará cada vez que la carga útil de la API cambie por cualquier motivo.
• Un vehículo desapareció después de una ejecución de cron. Compruebe si as24ci_full_sync está activado. Con la sincronización completa activada, cualquier listado que falte en la API se elimina de forma permanente (incluidos sus archivos adjuntos importados).
• Importer ran but no images were downloaded. Compruebe as24ci_import_images y as24ci_max_images. En las ejecuciones de cron/REST con as24ci_cron_image_queue = 1, solo la primera imagen se descarga inmediatamente y el resto se pospone para el procesador de la cola de imágenes.
• Skipping listing_id=… : lastModifiedDate unchanged. Esta es la línea de log detallada esperada para listados sin cambios; confirma que la detección de cambios está funcionando.

---

Documentos relacionados

• Image Importer And Queue
• Cron Events And Scheduler
• Architecture Overview
• Data Model
• Database Schema
• Section overview