Referencia de endpoints REST

Este apéndice enumera las rutas de la API REST registradas por el plugin ADP Car Market Hub bajo el espacio de nombres as24ci/v1.

Cuándo utilizar este documento

Utilice esta referencia cuando necesite llamar a un endpoint del plugin, cuando esté diagnosticando respuestas 403/404 inesperadas o cuando esté documentando una integración. Para la descripción conceptual de cada endpoint, consulte REST API Endpoints.

Descripción general

Todas las rutas registradas por el plugin utilizan la API REST de WordPress y comparten el espacio de nombres as24ci/v1. La URL completa de cualquier endpoint es la raíz REST de WordPress seguida de la ruta, normalmente https://example.com/wp-json/as24ci/v1/....

Los endpoints se dividen en cinco grupos:

1. Datos públicos de vehículos (/vehicles, /vehicles/{id}): desactivados por defecto; restringidos por as24ci_rest_api_enabled.
2. Asistente de favoritos (/favorites): utilizado por la página de favoritos del frontend.
3. Seguimiento de analíticas (/analytics/track): utilizado por el script del frontend.
4. Activador de importación por cron (/cron-import): protegido por token; utilizado por planificadores externos.
5. Señal de actualización de licencia (/license-refresh-signal): utilizado por la API Platform para solicitar al sitio que vuelva a validar su licencia.

Resumen de endpoints

GET /as24ci/v1/vehicles

Lista paginada y filtrable de vehículos importados cuyo estado de publicación es publish.

Parámetros de consulta:

Respuesta (estructura):

{
  "vehicles": [
    {
      "id": 0, "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
}

El campo image es el tamaño mediano-grande de la imagen destacada (cadena vacía si no hay ninguna). El campo currency recurre a as24ci_default_currency cuando no hay ninguna moneda guardada por vehículo.

GET /as24ci/v1/vehicles/{id}

Detalles completos de un solo vehículo.

• Parámetro de ruta: id — entero positivo; validado y convertido a través de absint.
• Autenticación: ninguna (público). Misma restricción que el endpoint de la lista.
• Respuesta: todos los campos de la respuesta de la lista más description, images (matriz de URLs de archivos adjuntos en tamaño large, combinando imágenes manuales e importadas y recurriendo a la imagen destacada), equipment_standard, equipment_optional y seller.
• Errores: 404 as24ci_vehicle_not_found cuando la publicación no existe, no es el CPT as24ci_car o no está publicada.

POST /as24ci/v1/favorites

Hidrata los favoritos del visitante con los datos actuales de los vehículos para los IDs almacenados en el almacenamiento local del navegador.

• Autenticación: ninguna (público). Siempre registrado.
• Cuerpo: objeto JSON con ids — una matriz de IDs de publicaciones. Saneado a una lista única de enteros positivos; limitado a un máximo de 50 IDs por solicitud.
• Respuesta: { "vehicles": [ ... ] }.
• Notas: Solo se devuelven vehículos publicados. Las publicaciones a las que el visitante ya no tiene acceso (eliminadas, borradores, tipo de publicación incorrecto) se omiten silenciosamente.

POST /as24ci/v1/analytics/track

Recibe eventos de analíticas desde el píxel de seguimiento del frontend.

• Autenticación: ninguna (público). Siempre registrado.
• Parámetros del cuerpo:
• post_id — entero ≥ 0. Por defecto 0.
• event_type — uno de view, view_archive, view_compare, view_favorites, filter_search, contact_open, lead_sent.
• extra_data — cadena saneada opcional. Para filter_search, debe ser un objeto JSON que contenga los pares clave/valor de los filtros activos.
• Respuesta: { "tracked": true } en caso de éxito, o { "tracked": false } con HTTP 400 cuando el evento requiere una publicación de vehículo que no existe o no está publicada.
• Notas: Intencionadamente permisivo para que los visitantes anónimos puedan enviar eventos. No dependa de él para obtener datos comerciales autoritativos.

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 gancho de WP-Cron y el botón manual de administración "Ejecutar ahora".

• Autenticación: token Bearer. Proporcione el token a través de la cabecera HTTP Authorization: Bearer <token> (preferido: mantiene el token fuera de los registros de acceso) o del parámetro de consulta ?token=<token>. La comparación utiliza hash_equals() para mitigar ataques de temporización.
• Almacenamiento del token: opción as24ci_cron_token. Genérelo o rótelo desde Importación y límites 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 se está ejecutando otra importación y el ejecutor rechazó iniciar una segunda.
• 500 cuando el ejecutor lanzó una excepción.
• Efecto secundario: Una autenticación exitosa actualiza as24ci_last_external_cron_run, que la pestaña de Sistema y Ayuda utiliza para confirmar que el cron externo se está comunicando con el sitio. Visitar cualquier URL con ?as24ci_cron=1 también actualiza esta marca de tiempo a través del gancho de latido en init.

Ejemplo de invocación de cron externo (marcador de posición: sustitúyalo por su propio host y un token generado):

0 * * * * curl -fsS -H "Authorization: Bearer YOUR_TOKEN" \
  "https://example.com/wp-json/as24ci/v1/cron-import?as24ci_cron=1"

POST /as24ci/v1/license-refresh-signal

Endpoint de señal ligero que permite a la API Platform solicitar al sitio que vuelva a validar su licencia fuera de banda (por ejemplo, después de un cambio de plan). Registrado incondicionalmente para que la plataforma siempre pueda comunicarse con él; no está restringido por la opción de la API REST pública de vehículos.

• Autenticación: modelo de confianza solo por señal. La autenticación se gestiona dentro del callback en lugar de mediante un permission_callback; la solicitud debe ser JSON y se valida contra la estructura de señal esperada.
• Cuerpo: objeto JSON. Los campos de correlación seguros y no secretos (request_id, event) se devuelven para fines de seguimiento únicamente.
• Respuestas:
• 405 method_not_allowed cuando la solicitud no es POST.
• 400 invalid_content_type cuando el cuerpo no es JSON, o 400 invalid_json cuando el cuerpo no se puede analizar.
• 200 cuando se acepta la señal.
• Propietario: AS24CI\License_Refresh_Signal.

Notas de funcionamiento

• 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 publicaciones y de metadatos de publicaciones.
• Los filtros numéricos se añaden a un 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 en la versión actual del plugin antes de publicar.
• El endpoint de la lista aplica update_postmeta_cache() en las publicaciones devueltas para mantener los tiempos de respuesta predecibles.
• El endpoint de favoritos limita estrictamente cada solicitud a un máximo de 50 IDs para evitar abusos.
• El endpoint de importación por cron establece nocache_headers() para que los proxies de caché no interfieran con las ejecuciones programadas.
• Se recomiendan enlaces permanentes bonitos para las URLs REST de tipo ruta. Con enlaces permanentes simples, los endpoints siguen siendo accesibles a través de ?rest_route=.

Resolución de problemas

• /vehicles devuelve 404. La API pública está desactivada. Establezca as24ci_rest_api_enabled en '1' en Ajustes → SEO e integraciones (o a través de WP-CLI / update_option).
• /cron-import devuelve 403. O bien no hay ningún token configurado (as24ci_cron_token vacío; el mensaje de respuesta lo confirma) o el token 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 finalice la ejecución actual.
• Matriz vehicles vacía en el endpoint de la lista sin filtros. No hay vehículos publicados o el catálogo aún no se ha importado. Compruebe la pantalla de Importación y límites y los registros de importación.
• HTTP 400 en /analytics/track. El evento requiere una publicación de vehículo publicada, pero post_id hace referencia a un borrador, una publicación eliminada o una publicación que no es de vehículo.

Documentos relacionados

• REST API Endpoints
• REST API For Developers
• Cron Hook Reference
• Webhook Event Reference
• Referencia de ajustes