Points de terminaison de l'API REST

Ce document décrit les routes de l'API REST enregistrées par le plugin ADP Car Market Hub sous le namespace as24ci/v1, y compris leurs méthodes, paramètres, modèle d'authentification et utilisation prévue.

Quand utiliser ce document

Lisez ce document si vous devez :

• Créer une intégration personnalisée qui consomme les données de véhicules du plugin via HTTP.
• Déclencher des importations à partir d'un planificateur externe au lieu de WP-Cron.
• Comprendre quels points de terminaison sont publics, lesquels sont protégés par un bouton d'activation contrôlé par l'administrateur, et lesquels nécessitent un jeton.
• Diagnostiquer les réponses 403 / 404 inattendues des routes REST du plugin.

Pour l'interface AJAX (admin-ajax.php), consultez Actions AJAX. Pour les appels HTTP sortants vers des systèmes externes, consultez Webhooks.

Aperçu

Toutes les routes enregistrées par le plugin utilisent l'API REST WordPress et partagent le namespace as24ci/v1. Les points de terminaison se répartissent en quatre groupes :

1. Données publiques de véhicules — points de terminaison de liste et de détail en lecture seule. Désactivés par défaut ; doivent être activés par un administrateur.
2. Assistant de favoris — utilisé par la page des favoris du front-end pour récupérer les données de véhicules pour les ID que le visiteur a stockés localement.
3. Pixel de suivi analytique — accepte des notifications d'événements légères provenant du script front-end.
4. Déclencheur d'importation Cron — point de terminaison protégé par jeton qui exécute la routine d'importation partagée à la demande.
5. Signal de rafraîchissement de licence — point de terminaison de signal uniquement que la plateforme API ADP Car Market Hub appelle pour que le plugin récupère à nouveau son état faisant foi de licence / droits de fonctionnalités.

L'URL de base complète de tout point de terminaison est la racine REST WordPress suivie par la route. Sur un site typique, il s'agit de https://example.com/wp-json/as24ci/v1/....

Configuration requise ou prérequis

• WordPress avec l'API REST activée (la valeur par défaut de WordPress).
• Permaliens personnalisés pour les URL REST de type chemin. Avec des permaliens simples, les points de terminaison sont toujours accessibles via ?rest_route=.
• Pour les points de terminaison publics de véhicules : l'option as24ci_rest_api_enabled doit être définie sur 1. Tant que ce n'est pas le cas, les routes ne sont pas enregistrées et toute requête renvoie un 404 de la part de WordPress.
• Pour le point de terminaison d'importation cron : un jeton cron doit être généré dans l'onglet d'administration Import & Limits.

Référence des points de terminaison

GET /as24ci/v1/vehicles

Renvoie une liste paginée et filtrable de véhicules importés dont le statut de publication CPT est publish.

• Authentification : aucune (public). La route est uniquement enregistrée lorsque as24ci_rest_api_enabled est égal à 1.
• Paramètres de requête :
• page — entier ≥ 1. Par défaut 1.
• per_page — entier entre 1 et 100. Par défaut 10.
• make, model — correspondance exacte avec les clés méta correspondantes.
• fuel_type — correspondance LIKE avec la clé méta du type de carburant mappé.
• year_min, year_max — plage numérique par rapport à _as24ci_year.
• price_min, price_max — plage numérique par rapport à _as24ci_price.
• orderby — l'un des suivants : date, price, mileage, title. Par défaut date.
• order — asc ou desc (insensible à la casse). Par défaut desc.
• Format de la réponse : ``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 } ``
• Notes : Le champ image est la taille moyenne-grande WordPress de l'image mise en avant (chaîne vide lorsqu'aucune miniature n'existe). Le champ currency utilise par défaut la valeur de l'option as24ci_default_currency lorsqu'aucune devise par véhicule n'est stockée.

GET /as24ci/v1/vehicles/<id>

Renvoie les détails complets d'un seul véhicule.

• Authentification : aucune (public). Même restriction que le point de terminaison de liste.
• Paramètre de chemin : id — entier positif. Validé et converti en absint.
• Réponse : Tous les champs de la réponse de liste plus :
• description — utilise l'extrait WordPress lorsqu'il est présent, sinon le contenu tronqué de la publication (≈55 mots).
• images — tableau d'URL de pièces jointes à la taille large, combinant les images de la galerie manuelle (_as24ci_manual_image_ids) et les images importées (_as24ci_image_ids) ; utilise par défaut l'image mise en avant lorsque les deux sont vides.
• equipment_standard, equipment_optional — tableaux de chaînes de caractères.
• seller — nom d'affichage du concessionnaire.
• Erreurs :
• 404 (as24ci_vehicle_not_found) lorsque la publication n'existe pas, n'est pas du CPT as24ci_car, ou n'est pas publiée.

POST /as24ci/v1/favorites

Utilisé par la page des favoris du front-end pour récupérer les données de résumé de véhicule pour les ID que le visiteur a stockés dans le stockage local du navigateur.

• Authentification : aucune (public). Toujours enregistré.
• Corps : Objet JSON avec ids, un tableau d'ID de publications. Validé comme étant un tableau ; nettoyé en une liste unique d'entiers positifs. Jusqu'à 50 ID sont traités par appel.
• Réponse : { "vehicles": [ ... ] }.
• Notes : Le point de terminaison lit uniquement les véhicules publiés. Les publications auxquelles le visiteur n'a plus accès (supprimées, brouillons, mauvais type de publication) sont ignorées silencieusement.

POST /as24ci/v1/analytics/track

Reçoit les événements de vue, vue d'archive, vue de comparaison, vue de favoris, recherche de filtre, ouverture de contact et lead envoyé depuis le pixel de suivi analytique.

• Authentification : aucune (public). Toujours enregistré.
• Paramètres du corps :
• post_id — entier ≥ 0. Par défaut 0.
• event_type — doit être l'un des noms d'événements autorisés : view, view_archive, view_compare, view_favorites, filter_search, contact_open, lead_sent.
• extra_data — chaîne nettoyée facultative. Pour filter_search, la chaîne doit être un objet JSON contenant les paires clé/valeur de filtre actives ; le serveur applique la même logique de minimisation que celle utilisée par le suivi PHP direct avant le stockage.
• Réponse : { "tracked": true } en cas de succès, { "tracked": false } avec HTTP 400 lorsque l'événement nécessite une publication de véhicule qui n'existe pas ou n'est pas publiée.
• Notes : Ce point de terminaison est intentionnellement permissif afin que les visiteurs anonymes puissent envoyer des événements analytiques. Ne vous y fiez pas pour des données commerciales faisant foi ; voir Suivi analytique pour les notes sur la conservation et la confidentialité.

GET /as24ci/v1/cron-import

Point de terminaison protégé par jeton qui exécute la routine d'importation partagée. Il délègue à la même méthode Scheduler::run_import() que celle utilisée par le crochet WP-Cron et le bouton d'administration Déclencher maintenant.

• Authentification : jeton porteur (bearer token). Fournissez le jeton soit via l'en-tête HTTP Authorization: Bearer <token> (préféré — évite que le jeton n'apparaisse dans les journaux d'accès) soit via le paramètre de requête ?token=<token>.
• Stockage du jeton : conservé dans l'option as24ci_cron_token. Générez-le ou renouvelez-le depuis Import & Limits dans l'administration du plugin.
• Réponses :
• 403 lorsqu'aucun jeton n'est configuré ou que le jeton fourni ne correspond pas.
• 200 avec { "success": true, "message": "...", "counts": { ... } } lors d'une exécution réussie.
• 429 avec success: false lorsqu'une autre importation est déjà en cours et que l'exécuteur a refusé d'en démarrer une seconde.
• 500 lorsque l'exécuteur a levé une exception.
• Effet secondaire : une authentification réussie met à jour l'option as24ci_last_external_cron_run, que l'onglet Système & Aide utilise pour confirmer que le cron externe accède bien au site.

POST /as24ci/v1/license-refresh-signal

Point de terminaison de signal uniquement que la plateforme API ADP Car Market Hub appelle après un changement de licence ou de droit de fonctionnalité afin que le plugin récupère immédiatement son état faisant foi. Détenu par AS24CI\License_Refresh_Signal et enregistré sans condition (comme /cron-import), indépendamment de as24ci_rest_api_enabled.

• Authentification : gérée à l'intérieur du rappel (callback) à l'aide d'un modèle de confiance basé uniquement sur le signal. Rien du corps de la requête n'est considéré comme une donnée fiable ; la requête déclenche uniquement License_Manager::refresh(). Le gestionnaire applique, dans l'ordre : POST + type de contenu JSON ; un product_key correspondant (par rapport à License_Client::PRODUCT_KEY) ; un installation_uid correspondant lorsque les deux parties en ont un ; une licence locale configurée ; un secret de signal de rafraîchissement provisionné par installation ; un en-tête d'horodatage récent et un nonce inutilisé (protection contre le rejeu, fenêtre de 5 minutes) ; et une signature HMAC-SHA256 sur l'horodatage + le corps brut.
• Limitation du débit : les signaux répétés dans une fenêtre de 30 secondes sont acceptés mais non rafraîchis et reçoivent la réponse 429 afin qu'une rafale ne puisse jamais surcharger la plateforme API.
• Réponses : 200 lors d'un rafraîchissement déclenché ; 4xx/503 pour les échecs de validation ci-dessus (403 non-correspondance produit/installation, 409 non licencié / nonce rejoué, 401 mauvais horodatage/signature, 503 lorsqu'aucun secret de signal n'est provisionné).

Notes opérationnelles

• Les points de terminaison publics de véhicules exécutent des appels WP_Query standard et respectent la mise en cache d'objets WordPress normale. Les requêtes identiques répétées bénéficient des caches de publications et de méta-données de publications.
• Les filtres numériques (year_min/year_max, price_min/price_max) sont ajoutés à une meta_query. Sur les grands catalogues, assurez-vous que les clés méta sous-jacentes sont indexées au niveau de la base de données si vous attendez un trafic important. Vérifiez la stratégie d'indexation exacte dans la version actuelle du plugin avant de publier.
• Le point de terminaison de liste applique update_postmeta_cache() pour les publications renvoyées afin de maintenir des temps de réponse prévisibles.
• Le point de terminaison des favoris limite strictement chaque requête à 50 ID pour éviter les abus et maintenir des charges utiles de réponse raisonnables.
• Le point de terminaison d'importation cron définit nocache_headers() afin que les proxys de mise en cache n'interfèrent pas avec les exécutions planifiées.
• La comparaison des jetons utilise hash_equals() pour atténuer les attaques temporelles. Malgré cela, préférez l'en-tête Authorization: Bearer pour éviter de divulguer le jeton via les en-têtes de référent (referrer), l'historique du navigateur ou les journaux d'accès du serveur web.

Référence de configuration

Pour la liste complète des options du plugin, consultez Stockage des options et des réglages.

Dépannage

• /vehicles renvoie 404 — l'API publique est désactivée. Définissez as24ci_rest_api_enabled sur '1' dans Import & Limits (ou via WP-CLI / update_option).
• /cron-import renvoie 403 — soit aucun jeton n'est encore configuré, soit la valeur fournie ne correspond pas. Générez un nouveau jeton depuis l'administration et réessayez.
• /cron-import renvoie 429 — une autre importation est déjà en cours et un verrou empêche une deuxième exécution simultanée. Attendez que l'exécution en cours se termine ; consultez Événements Cron et planificateur pour connaître le TTL du verrou.
• Tableau vehicles vide sur le point de terminaison de liste sans filtre — aucun véhicule n'est publié, ou le catalogue n'a pas encore été importé. Vérifiez Import & Limits et les journaux d'importation.
• HTTP 400 inattendu sur /analytics/track — l'événement nécessite une publication de véhicule publiée mais post_id fait référence à un brouillon, une publication supprimée ou une publication qui n'est pas un véhicule.

Documents connexes

• Actions AJAX
• Webhooks
• Événements Cron et planificateur
• Stockage des options et des réglages
• Suivi analytique
• Sécurité et fonctionnalités