Référence des points de terminaison REST

Cette annexe répertorie les routes de l'API REST enregistrées par l'extension ADP Car Market Hub sous le namespace as24ci/v1.

Quand utiliser ce document

Utilisez cette référence lorsque vous devez appeler un point de terminaison de l'extension, lorsque vous diagnostiquez des réponses 403/404 inattendues, ou lorsque vous documentez une intégration. Pour la description conceptuelle de chaque point de terminaison, consultez Points de terminaison de l'API REST.

Aperçu

Toutes les routes enregistrées par l'extension utilisent l'API REST de WordPress et partagent le namespace as24ci/v1. L'URL complète de tout point de terminaison est la racine REST de WordPress suivie de la route, généralement https://example.com/wp-json/as24ci/v1/....

Les points de terminaison se répartissent en cinq groupes :

1. Données publiques des véhicules (/vehicles, /vehicles/{id}) — désactivées par défaut ; contrôlées par as24ci_rest_api_enabled.
2. Assistant de favoris (/favorites) — utilisé par la page des favoris du front-end.
3. Suivi analytique (/analytics/track) — utilisé par le script du front-end.
4. Déclencheur d'importation Cron (/cron-import) — protégé par jeton ; utilisé par les planificateurs externes.
5. Signal de renouvellement de licence (/license-refresh-signal) — utilisé par l'API Platform pour demander au site de revalider sa licence.

Résumé des points de terminaison

GET /as24ci/v1/vehicles

Liste paginée et filtrable des véhicules importés dont le statut de publication est publish.

Paramètres de requête :

Réponse (structure) :

{
  "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
}

Le champ image correspond à la taille moyenne-grande de l'image mise en avant (chaîne vide si aucune). Le champ currency se rabat sur as24ci_default_currency lorsqu'aucune devise par véhicule n'est stockée.

GET /as24ci/v1/vehicles/{id}

Détails complets pour un seul véhicule.

• Paramètre de chemin : id — entier positif ; validé et converti via absint.
• Authentification : aucune (publique). Même contrôle que le point de terminaison de liste.
• Réponse : tous les champs de la réponse de liste plus description, images (tableau d'URL de pièces jointes à la taille large, combinant les images manuelles et importées et se rabattant sur l'image mise en avant), equipment_standard, equipment_optional et seller.
• Erreurs : 404 as24ci_vehicle_not_found lorsque la publication n'existe pas, n'est pas le CPT as24ci_car, ou n'est pas publiée.

POST /as24ci/v1/favorites

Hydrate les favoris du visiteur avec les données actuelles des véhicules pour les ID stockés dans le stockage local du navigateur.

• Authentification : aucune (publique). Toujours enregistré.
• Corps : objet JSON avec ids — un tableau d'ID de publications. Nettoyé pour obtenir une liste unique d'entiers positifs ; limité à 50 ID par requête.
• Réponse : { "vehicles": [ ... ] }.
• Notes : Seuls les véhicules publiés sont renvoyés. Les publications auxquelles le visiteur n'a plus accès (supprimées, brouillons, mauvais type de publication) sont omises silencieusement.

POST /as24ci/v1/analytics/track

Reçoit les événements analytiques du pixel de suivi front-end.

• Authentification : aucune (publique). Toujours enregistré.
• Paramètres du corps :
• post_id — entier ≥ 0. Par défaut 0.
• event_type — l'un des suivants : view, view_archive, view_compare, view_favorites, filter_search, contact_open, lead_sent.
• extra_data — chaîne nettoyée facultative. Pour filter_search, doit être un objet JSON contenant les paires clé/valeur des filtres actifs.
• Réponse : { "tracked": true } en cas de succès, ou { "tracked": false } avec le code HTTP 400 lorsque l'événement nécessite une publication de véhicule qui n'existe pas ou n'est pas publiée.
• Notes : Volontairement permissif pour que les visiteurs anonymes puissent envoyer des événements. Ne vous y fiez pas pour des données commerciales faisant autorité.

GET /as24ci/v1/cron-import

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

• Authentification : jeton bearer. 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>. La comparaison utilise hash_equals() pour atténuer les attaques temporelles.
• Stockage du jeton : option as24ci_cron_token. Générez-le ou renouvelez-le depuis Import & Limits dans l'administration de l'extension.
• 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 le lanceur a refusé d'en démarrer une seconde.
• 500 lorsque le lanceur a levé une exception.
• Effet secondaire : Une authentification réussie met à jour as24ci_last_external_cron_run, que l'onglet Système et aide utilise pour confirmer que le cron externe accède bien au site. Visiter n'importe quelle URL avec ?as24ci_cron=1 met également à jour cet horodatage via le hook de pulsation (heartbeat) sur init.

Exemple d'appel cron externe (espace réservé — remplacez par votre propre hôte et un jeton généré) :

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

Point de terminaison de signal léger qui permet à l'API Platform de demander au site de revalider sa licence hors bande (par exemple après un changement d'abonnement). Enregistré de manière inconditionnelle pour que la plateforme puisse toujours l'atteindre ; il n'est pas soumis à l'option de l'API REST publique des véhicules.

• Authentification : modèle de confiance basé uniquement sur le signal. L'authentification est gérée à l'intérieur du callback plutôt que par un permission_callback ; la requête doit être au format JSON et est validée par rapport à la structure de signal attendue.
• Corps : objet JSON. Les champs de corrélation sécurisés et non secrets (request_id, event) sont renvoyés en écho uniquement pour le suivi.
• Réponses :
• 405 method_not_allowed lorsque la requête n'est pas POST.
• 400 invalid_content_type lorsque le corps n'est pas en JSON, ou 400 invalid_json lorsque le corps ne peut pas être analysé.
• 200 lorsque le signal est accepté.
• Propriétaire : AS24CI\License_Refresh_Signal.

Notes opérationnelles

• Les points de terminaison publics des véhicules exécutent des appels WP_Query standards et respectent la mise en cache d'objets normale de WordPress. 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 s'ajoutent à 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 prévoyez un trafic important. Vérifiez la stratégie d'indexation dans la version actuelle de l'extension avant de publier.
• Le point de terminaison de liste applique update_postmeta_cache() sur les publications renvoyées pour 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.
• 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.
• Les permaliens personnalisés (pretty permalinks) sont recommandés pour les URL REST de type chemin. Avec des permaliens simples, les points de terminaison restent accessibles via ?rest_route=.

Dépannage

• /vehicles renvoie 404. L'API publique est désactivée. Définissez as24ci_rest_api_enabled sur '1' dans Réglages → SEO & Intégrations (ou via WP-CLI / update_option).
• /cron-import renvoie 403. Soit aucun jeton n'est configuré (as24ci_cron_token est vide — le message de réponse le confirme), soit le jeton fourni 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 actuelle se termine.
• Tableau vehicles vide sur le point de terminaison de liste sans aucun filtre. Aucun véhicule n'est publié, ou le catalogue n'a pas encore été importé. Vérifiez l'écran Import & Limits et les journaux d'importation.
• HTTP 400 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

• Points de terminaison de l'API REST
• API REST pour les développeurs
• Référence du hook Cron
• Référence des événements Webhook
• Référence des réglages