Endpoints de la REST API

Este documento describe las rutas de la REST API registradas por el plugin ADP Car Market Hub bajo el espacio de nombres as24ci/v1, incluyendo sus métodos, parámetros, modelo de autenticación y uso previsto.

Cuándo usar este documento

Lea este documento si necesita:

• Construir una integración personalizada que consuma datos de vehículos desde el plugin a través de HTTP.
• Activar importaciones desde un programador externo en lugar de WP-Cron.
• Entender qué endpoints son públicos, cuáles están protegidos por un conmutador controlado por el administrador y cuáles requieren un token.
• Diagnosticar respuestas 403 / 404 inesperadas de las rutas REST del plugin.

Para la interfaz AJAX (admin-ajax.php), consulte Acciones AJAX. Para llamadas HTTP salientes a sistemas externos, consulte Webhooks.

Descripción general

Todas las rutas registradas por el plugin utilizan la REST API de WordPress y comparten el espacio de nombres as24ci/v1. Los endpoints se dividen en cuatro grupos:

1. Datos públicos de vehículos — endpoints de lectura de listados y detalles. Desactivados por defecto; deben ser activados por un administrador.
2. Ayudante de favoritos — utilizado por la página de favoritos del frontend para obtener datos de vehículos para los ID que el visitante ha almacenado localmente.
3. Píxel de seguimiento de Analytics — acepta notificaciones de eventos ligeras desde el script del frontend.
4. Activador de importación por Cron — endpoint protegido por token que ejecuta la rutina de importación compartida bajo demanda.
5. Señal de actualización de licencia — endpoint solo de señal que la plataforma de la API de ADP Car Market Hub llama para que el plugin vuelva a obtener su estado autorizado de licencia / derechos de características.

La URL base completa de cualquier endpoint es la raíz REST de WordPress seguida de la ruta. En un sitio típico, esto es https://example.com/wp-json/as24ci/v1/....

Requisitos o requisitos previos

• WordPress con la REST API habilitada (el valor por defecto de WordPress).
• Enlaces permanentes bonitos para URLs REST de tipo ruta. Con enlaces permanentes simples, los endpoints siguen siendo accesibles a través de ?rest_route=.
• Para los endpoints públicos de vehículos: la opción as24ci_rest_api_enabled debe estar establecida en 1. Hasta entonces, las rutas no se registran y cualquier solicitud devuelve un 404 de WordPress.
• Para el endpoint de importación por cron: se debe generar un token de cron en la pestaña de administración Import & Limits.

Referencia de endpoints

GET /as24ci/v1/vehicles

Devuelve una lista paginada y filtrable de vehículos importados cuyo estado de entrada del CPT es publish.

• Autenticación: ninguna (público). La ruta solo se registra cuando as24ci_rest_api_enabled es igual a 1.
• Parámetros de consulta:
• page — entero ≥ 1. Por defecto 1.
• per_page — entero entre 1 y 100. Por defecto 10.
• make, model — coincidencia exacta con las claves meta correspondientes.
• fuel_type — coincidencia LIKE con la clave meta del tipo de combustible mapeado.
• year_min, year_max — rango numérico contra _as24ci_year.
• price_min, price_max — rango numérico contra _as24ci_price.
• orderby — uno de date, price, mileage, title. Por defecto date.
• order — asc o desc (insensible a mayúsculas/minúsculas). Por defecto desc.
• Estructura de la respuesta: ``json { "vehicles": [ { "id": 123, "title": "...", "url": "...", "image": "...", "make": "...", "model": "...", "year": 0, "price": 0, "currency": "EUR", "mileage": 0, "condition": "...", "fuel_type": "...", "transmission": "...", "body_type": "...", "color": "...", "doors": 0, "horse_power": 0, "vin": "...", "listing_id": "..." } ], "total": 0, "pages": 0, "page": 1, "per_page": 10 } ``
• Notas: El campo image es el tamaño mediano-grande de WordPress de la imagen destacada (cadena vacía cuando no existe miniatura). El campo currency recurre al valor de la opción as24ci_default_currency cuando no hay ninguna moneda almacenada por vehículo.

GET /as24ci/v1/vehicles/<id>

Devuelve los detalles completos de un solo vehículo.

• Autenticación: ninguna (público). Mismo control de acceso que el endpoint de la lista.
• Parámetro de ruta: id — entero positivo. Validado y convertido a absint.
• Respuesta: Todos los campos de la respuesta de la lista más:
• description — utiliza el extracto de WordPress cuando está presente, de lo contrario el contenido recortado de la entrada (≈55 palabras).
• images — array de URLs de archivos adjuntos en el tamaño large, combinando imágenes de la galería manual (_as24ci_manual_image_ids) e imágenes importadas (_as24ci_image_ids); recurre a la imagen destacada cuando ambos están vacíos.
• equipment_standard, equipment_optional — arrays de cadenas.
• seller — nombre visible del concesionario.
• Errores:
• 404 (as24ci_vehicle_not_found) cuando la entrada no existe, no es el CPT as24ci_car o no está publicada.

POST /as24ci/v1/favorites

Utilizado por la página de favoritos del frontend para obtener datos de resumen de vehículos para los ID que el visitante ha almacenado en el almacenamiento local del navegador.

• Autenticación: ninguna (público). Siempre registrado.
• Cuerpo: Objeto JSON con ids, un array de ID de entradas. Validado para ser un array; saneado a una lista única de enteros positivos. Se procesan hasta 50 ID por llamada.
• Respuesta: { "vehicles": [ ... ] }.
• Notas: El endpoint lee solo vehículos publicados. Las entradas a las que el visitante ya no tiene acceso (eliminadas, borrador, tipo de entrada incorrecto) se omiten silenciosamente.

POST /as24ci/v1/analytics/track

Recibe eventos de visualización, visualización de archivo, visualización de comparación, visualización de favoritos, búsqueda de filtros, apertura de contacto y envío de leads desde el píxel de seguimiento de analytics.

• Autenticación: ninguna (público). Siempre registrado.
• Parámetros del cuerpo:
• post_id — entero ≥ 0. Por defecto 0.
• event_type — debe ser uno de los nombres de eventos permitidos: view, view_archive, view_compare, view_favorites, filter_search, contact_open, lead_sent.
• extra_data — cadena opcional saneada. Para filter_search, la cadena debe ser un objeto JSON que contenga los pares clave/valor del filtro activo; el servidor aplica la misma lógica de minimización utilizada por el seguimiento directo de PHP antes de almacenar.
• Respuesta: { "tracked": true } en caso de éxito, { "tracked": false } con HTTP 400 cuando el evento requiere una entrada de vehículo que no existe o no está publicada.
• Notas: Este endpoint es intencionadamente permisivo para que los visitantes anónimos puedan enviar eventos de analytics. No confíe en él para datos comerciales autoritativos; consulte Analytics Tracking para notas sobre retención y privacidad.

GET /as24ci/v1/cron-import

Endpoint protegido por token que ejecuta la rutina de importación compartida. Delega en el mismo método Scheduler::run_import() utilizado por el hook de WP-Cron y el botón de administración Trigger now.

• Autenticación: token portador (bearer token). Proporcione el token a través de la cabecera HTTP Authorization: Bearer <token> (preferido — mantiene el token fuera de los registros de acceso) o el parámetro de consulta ?token=<token>.
• Almacenamiento del token: persistido en la opción as24ci_cron_token. Genérelo o rótelo desde Import & Limits en la administración del plugin.
• Respuestas:
• 403 cuando no hay ningún token configurado o el token proporcionado no coincide.
• 200 con { "success": true, "message": "...", "counts": { ... } } en una ejecución exitosa.
• 429 con success: false cuando ya hay otra importación en curso y el ejecutor rechazó iniciar una segunda.
• 500 cuando el ejecutor lanzó una excepción.
• Efecto secundario: una autenticación exitosa actualiza la opción as24ci_last_external_cron_run, que la pestaña System & Help utiliza para confirmar que el cron externo está llegando al sitio.

POST /as24ci/v1/license-refresh-signal

Endpoint solo de señal que la plataforma de la API de ADP Car Market Hub llama después de un cambio de licencia o de derechos de características para que el plugin vuelva a obtener su estado autorizado de inmediato. Propiedad de AS24CI\License_Refresh_Signal y registrado incondicionalmente (como /cron-import), independientemente de as24ci_rest_api_enabled.

• Autenticación: gestionada dentro de la función de devolución de llamada (callback) utilizando un modelo de confianza solo de señal. No se confía en nada del cuerpo de la solicitud como datos; la solicitud solo activa License_Manager::refresh(). El controlador aplica, en orden: POST + tipo de contenido JSON; un product_key coincidente (contra License_Client::PRODUCT_KEY); un installation_uid coincidente cuando ambas partes tienen uno; una licencia local configurada; un secreto de señal de actualización aprovisionado por instalación; una cabecera de marca de tiempo reciente y un nonce no utilizado (protección contra reproducción, ventana de 5 minutos); y una firma HMAC-SHA256 sobre la marca de tiempo + el cuerpo sin procesar.
• Límite de frecuencia: las señales repetidas dentro de una ventana de 30 segundos son aceptadas pero no actualizadas, y se responden con 429 para que una ráfaga nunca sature la plataforma de la API.
• Respuestas: 200 en una actualización activada; 4xx/503 para los fallos de validación anteriores (403 discrepancia de producto/instalación, 409 sin licencia / nonce reproducido, 401 marca de tiempo/firma incorrecta, 503 cuando no hay ningún secreto de señal aprovisionado).

Notas operativas

• Los endpoints públicos de vehículos ejecutan llamadas estándar de WP_Query y respetan el almacenamiento en caché de objetos normal de WordPress. Las solicitudes idénticas repetidas se benefician de las cachés de entradas y meta de entradas.
• Los filtros numéricos (year_min/year_max, price_min/price_max) se añaden a una meta_query. En catálogos grandes, asegúrese de que las claves meta subyacentes estén indexadas a nivel de base de datos si espera un tráfico pesado. Verifique la estrategia de indexación exacta en la versión actual del plugin antes de publicar.
• El endpoint de la lista aplica update_postmeta_cache() para las entradas devueltas para mantener los tiempos de respuesta predecibles.
• El endpoint de favoritos limita estrictamente cada solicitud a 50 ID para evitar abusos y mantener los datos de respuesta en un tamaño razonable.
• El endpoint de importación por cron establece nocache_headers() para que los proxies de caché no interfieran con las ejecuciones programadas.
• La comparación de tokens utiliza hash_equals() para mitigar los ataques de tiempo. Aun así, prefiera la cabecera Authorization: Bearer para evitar la filtración del token a través de cabeceras de referencia, el historial del navegador o los registros de acceso del servidor web.

Referencia de configuración

Para obtener la lista completa de opciones del plugin, consulte Options And Settings Storage.

Resolución de problemas

• /vehicles devuelve 404 — la API pública está desactivada. Establezca as24ci_rest_api_enabled en '1' en Import & Limits (o a través de WP-CLI / update_option).
• /cron-import devuelve 403 — o bien no se ha configurado ningún token todavía, o el valor proporcionado no coincide. Genere un nuevo token desde la administración y vuelva a intentarlo.
• /cron-import devuelve 429 — ya se está ejecutando otra importación y un bloqueo impide una segunda ejecución concurrente. Espere a que termine la ejecución actual; consulte Cron Events And Scheduler para ver el TTL del bloqueo.
• Array vehicles vacío en el endpoint de la lista sin filtros — no hay vehículos publicados, o el catálogo aún no se ha importado. Compruebe Import & Limits y los registros de importación.
• HTTP 400 inesperado en /analytics/track — el evento requiere una entrada de vehículo publicada, pero post_id hace referencia a un borrador, una entrada eliminada o que no es de vehículo.

Documentos relacionados

• AJAX Actions
• Webhooks
• Cron Events And Scheduler
• Options And Settings Storage
• Analytics Tracking
• Security And Capabilities