Documentación · Guía de integración

Configuración de la API de AutoScout24

Este documento explica cómo el acceso a la API de AutoScout24 se integra en el plugin ADP Car Market Hub, qué credenciales necesita el plugin y cómo un administrador puede validar que la cuenta del concesionario es accesible desde el sitio de WordPress.

El enfoque aquí es la parte de integración del trabajo: la relación entre el plugin, la cuenta de AutoScout24 del concesionario y las personas que suministran el acceso a la API. Para ver el recorrido paso a paso por los campos de la página de ajustes, consulte la Configuración de Credenciales de la API.

Cuándo usar este documento

Use este documento si está:

Planificando una nueva integración del plugin con el acceso a la API de AutoScout24 de un concesionario.
Verificando que un concesionario realmente tiene el tipo de acceso a la API que requiere el plugin antes de comenzar la configuración de WordPress.
Coordinándose con un socio de integración o con el contacto de TI del concesionario para obtener o rotar los valores de acceso a la API.
Validando después de la configuración que el sitio de WordPress puede comunicarse con la API de AutoScout24.

El público objetivo es un administrador o integrador de WordPress que trabaja junto con quien gestione el acceso a la API de AutoScout24 del concesionario. AD Promotion no emite accesos a la API de AutoScout24; las credenciales siempre provienen de la propia cuenta del concesionario o del socio que suministra el acceso en nombre del concesionario.

Descripción general

ADP Car Market Hub está diseñado en torno a la API oficial de AutoScout24. El plugin se autentica con un flujo de client credentials de OAuth2 contra un host de API que configura el administrador, solicita un token de acceso y luego llama a los endpoints de listados para importar vehículos en el tipo de contenido personalizado (CPT) as24ci_car.

En la práctica, la integración involucra a tres partes independientes:

El concesionario. Propietario de la cuenta de AutoScout24 y de los datos de los vehículos del concesionario.
El proveedor de la API. AutoScout24, o un socio de integración que expone los datos de AutoScout24 a través de una pasarela equivalente. Esta parte emite la URL base de la API, el Seller ID (o IDs), y el Client ID / Client Secret de OAuth.
El sitio de WordPress. Contiene la configuración del plugin, almacena las credenciales en la tabla de opciones de WordPress y realiza las importaciones periódicas.

El plugin utiliza exactamente el host de la API y las credenciales que usted configure; no hay ningún host de AutoScout24 codificado de forma fija dentro del plugin. Esto hace posible apuntar la misma instalación del plugin a diferentes entornos (por ejemplo, un entorno de pruebas o sandbox y la API de producción para el sitio en vivo) simplemente cambiando la configuración.

Requisitos previos

Antes de configurar la conexión de la API del plugin, confirme todo lo siguiente:

El concesionario tiene acceso a la API de AutoScout24 (o a una pasarela de integración equivalente) para el Seller ID (o IDs) que se deben importar. El inicio de sesión estándar del sitio web de concesionarios de AutoScout24 no es una credencial de API y no puede ser utilizado por el plugin.
Ha recibido, a través de un canal seguro, los valores que el plugin necesita:
URL base de la API – la URL HTTPS completa del entorno de AutoScout24 o de la pasarela del socio.
Seller ID (uno o más) – el identificador estable de la cuenta (o identificadores) emitido por el proveedor de la API. El Seller ID no es el nombre público del concesionario en el sitio web de AutoScout24.
Client ID – el identificador de cliente de OAuth.
Client Secret – la clave secreta de cliente de OAuth que se empareja con el Client ID.
El sitio de WordPress cumple con los requisitos de hosting, PHP y base de datos y requisitos de API, red y SSL. Se debe permitir el tráfico HTTPS saliente hacia el host de la API.
Se dispone de una cuenta de administrador en el sitio de WordPress.

Si alguno de estos valores es desconocido, no los invente. Póngase en contacto con la parte que suministró el acceso a la API del concesionario y solicítelos a través de un canal seguro.

Instrucciones paso a paso

El recorrido detallado de la interfaz de usuario de Ajustes se encuentra en la Configuración de Credenciales de la API. El flujo de integración general es:

Confirmar el acceso a la API con el proveedor. Verifique que el acceso a la API del concesionario esté activo, que el par Client ID / Client Secret sea válido y que las credenciales estén autorizadas para cada Seller ID que deba importarse. Los concesionarios con múltiples sedes o vendedores suelen necesitar una autorización explícita por cada Seller ID.
Recibir los valores de forma segura. Utilice un gestor de contraseñas, un mensaje cifrado u otro método seguro de transferencia de archivos. No acepte credenciales por correo electrónico simple o chat.
Configurar el plugin. En WordPress, abra Car Market Hub → Settings e introduzca la URL base de la API, el Seller ID, el Client ID y el Client Secret en la tarjeta API Connection & General Settings.
Ejecutar la prueba de conexión. Abra Car Market Hub → Tools y ejecute la prueba de conexión de la API como se describe en la Prueba de conexión. No comience a importar vehículos hasta que la prueba tenga éxito.
Ejecutar primero una importación pequeña. Utilice el Batch-Wizard o una única ejecución programada con un límite bajo de vehículos antes de habilitar la automatización completa. Esto valida el comportamiento de extremo a extremo sin importar todo el catálogo en el primer intento.
Habilitar las importaciones programadas. Una vez que la importación manual funcione, habilite WP-Cron o configure un activador de cron del servidor. Consulte la Configuración del Cron del Servidor.

Si algo falla en el camino, consulte los Errores de conexión de la API antes de ajustar la configuración.

Referencia de configuración

El plugin expone únicamente los campos necesarios para comunicarse con el entorno de AutoScout24 configurado. Las etiquetas a continuación coinciden con las etiquetas en Car Market Hub → Settings.

Campo	Propósito	Origen
API Base URL	URL HTTPS completa del entorno de AutoScout24 o de la pasarela del socio. El plugin utiliza esta URL exactamente como está configurada.	Proporcionada por AutoScout24 o por el socio de integración.
Seller ID	Uno o más identificadores de cuenta de concesionario. Los múltiples Seller IDs se introducen separados por comas.	Proporcionado junto con el acceso a la API. No es el nombre público del concesionario en el sitio web de AutoScout24.
Client ID	Identificador de cliente de OAuth. Trátelo como confidencial aunque técnicamente no sea secreto.	Emitido por el proveedor de la API.
Client Secret	Clave secreta de cliente de OAuth. Se almacena en la tabla de opciones de WordPress; trátela como una credencial sensible.	Emitida por el proveedor de la API. Si se pierde, normalmente debe volver a emitirse; no se puede recuperar.
Default currency	Se utiliza cuando un listado importado no proporciona un valor de moneda. No es una credencial.	Elegida por el administrador en función del mercado del concesionario.

El plugin deriva automáticamente el endpoint del token de OAuth y la audiencia del token a partir de la URL base de la API configurada; no hay un campo de interfaz de usuario independiente para ellos. Si el proveedor de la API requiere valores no estándar, póngase en contacto con AD Promotion o con el socio de integración antes de cambiar nada; la derivación estándar es lo que la mayoría de los entornos esperan.

Notas operativas

Almacenamiento. Las credenciales se almacenan como opciones de WordPress. Cualquier persona con acceso de administrador a WordPress, acceso al sistema de archivos de la base de datos o acceso a una copia de seguridad de la base de datos puede leerlas. Aplique las mismas protecciones que para cualquier otro secreto que gestione su organización.
Caché de tokens. El plugin solicita un token de acceso OAuth antes de su primera llamada a la API y lo almacena en caché. Las importaciones posteriores reutilizan el token almacenado en caché hasta que expira. Después de rotar las credenciales, es una buena práctica borrar la caché de tokens desde Car Market Hub → Tools para que la siguiente solicitud utilice las nuevas credenciales de inmediato.
Instalaciones multi-entorno. El plugin no tiene un interruptor integrado de producción / sandbox. Cambiar de entorno significa cambiar la URL base de la API, el Seller ID, el Client ID y el Client Secret por los valores del entorno de destino y ejecutar la prueba de conexión de nuevo. Utilice credenciales separadas por cada entorno de WordPress para que la actividad de pruebas no pueda interferir accidentalmente con los datos de producción.
Concesionarios con múltiples vendedores. Cuando se configuran varios Seller IDs, todos ellos se consultan con el mismo Client ID / Client Secret. Las credenciales deben estar autorizadas para cada Seller ID de la lista; de lo contrario, los vendedores individuales fallarán con un error de autorización durante la importación.
Registro de logs. Las llamadas a la API y las solicitudes de tokens se registran en el directorio de logs del plugin en wp-content/uploads/as24ci-logs/. Los logs incluyen suficientes detalles para diagnosticar problemas, pero el Client Secret no se escribe en texto plano. Trate el directorio de logs como confidencial.
Coordinación con el proveedor de la API. El plugin solo puede hacer lo que el proveedor de la API permite. Si el acceso a la API del concesionario se suspende, se limita o se restringe a un subconjunto de Seller IDs, el plugin informará de esos fallos pero no podrá evitarlos. Plantee siempre estos problemas a la parte que suministró el acceso.

Validando el acceso a la cuenta

Después de configurar el plugin, valide el acceso en este orden:

Prueba de conexión. Ejecute la prueba de conexión de la API en Car Market Hub → Tools. Un resultado exitoso confirma que la URL base de la API es accesible, que el flujo de OAuth tiene éxito y que el primer Seller ID configurado es reconocido por la API. Consulte la Prueba de conexión.
Importación manual de un lote pequeño. Utilice el Batch-Wizard para importar un número pequeño de vehículos. Confirme que los listados aparecen en Car Market Hub → Cars y que los precios, la moneda y los atributos básicos se muestran correctamente.
Comprobación de la importación de imágenes. Confirme que la primera imagen de cada vehículo de prueba se descargó y se adjuntó correctamente. Si el procesamiento de imágenes está en cola, verifique el estado de la cola de imágenes en Car Market Hub → Import & Limits.
Pestaña System & Help. Revise los indicadores de diagnóstico en la pestaña System & Help para confirmar que no hay advertencias pendientes sobre la conectividad de la API, la programación o el almacenamiento.

Verifique este flujo de validación en la versión actual del plugin antes de publicar instrucciones dirigidas al cliente, ya que las etiquetas de la interfaz de usuario pueden evolucionar entre versiones.

Resolución de problemas

Síntoma	Causa probable	Qué comprobar
La prueba de conexión informa de un error de autenticación.	Client ID / Client Secret incorrectos, entorno no coincidente o espacios en blanco pegados en un campo de credencial.	Vuelva a introducir tanto el Client ID como el Client Secret. Confirme con el proveedor de la API que los valores son válidos para la URL base de la API configurada.
La prueba de conexión informa "no Seller ID configured".	El campo Seller ID no se guardó o contiene solo espacios en blanco / una coma suelta.	Vuelva a abrir Ajustes, introduzca de nuevo el Seller ID y guarde otra vez.
La prueba de conexión falla con un error de red o SSL.	El tráfico HTTPS saliente hacia el host de la API está bloqueado, el paquete CA del servidor está desactualizado o el DNS no resuelve el host.	Consulte los requisitos de API, red y SSL y los Errores de conexión de la API.
La conexión funciona pero no se importan vehículos para un Seller ID específico.	Las credenciales no están autorizadas para ese Seller ID, o el vendedor no tiene listados publicados.	Póngase en contacto con el proveedor de la API para confirmar la autorización. Verifique en la cuenta de AutoScout24 del concesionario que los listados estén activos.
Después de rotar las credenciales, parece que todavía se usan las antiguas.	El token de acceso almacenado en caché aún no ha expirado.	Borre la caché de tokens desde Car Market Hub → Tools y vuelva a ejecutar la prueba de conexión.
La importación funciona parcialmente pero algunos vehículos fallan repetidamente.	Problemas de datos en el lado del proveedor o limitación de tasa (rate limiting) en la API.	Revise los logs del plugin en `wp-content/uploads/as24ci-logs/` y reporte los fallos repetibles al proveedor de la API con los fragmentos de log pertinentes (con los secretos ocultos).