Endpoint delle REST API

Questo documento descrive le rotte REST API registrate dal plugin ADP Car Market Hub sotto il namespace as24ci/v1, inclusi i loro metodi, parametri, modello di autenticazione e uso previsto.

Quando utilizzare questo documento

Leggere questo documento se si ha la necessità di:

• Creare un'integrazione personalizzata che consumi i dati dei veicoli dal plugin tramite HTTP.
• Avviare le importazioni da un pianificatore esterno invece che tramite WP-Cron.
• Capire quali endpoint sono pubblici, quali sono protetti da un'opzione controllata dall'amministratore e quali richiedono un token.
• Diagnosticare risposte 403 / 404 impreviste dalle rotte REST del plugin.

Per l'interfaccia AJAX (admin-ajax.php), consultare la guida Azioni AJAX. Per le chiamate HTTP in uscita verso sistemi esterni, consultare la guida Webhook.

Panoramica

Tutte le rotte registrate dal plugin utilizzano la REST API di WordPress e condividono il namespace as24ci/v1. Gli endpoint si dividono in quattro gruppi:

1. Dati pubblici dei veicoli — endpoint di elenco e dettaglio in sola lettura. Disabilitati per impostazione predefinita; devono essere attivati da un amministratore.
2. Helper per i preferiti — utilizzato dalla pagina dei preferiti del frontend per recuperare i dati dei veicoli per gli ID che il visitatore ha memorizzato localmente.
3. Pixel di tracciamento di Analytics — accetta notifiche di eventi leggere dal codice script del frontend.
4. Trigger di importazione tramite Cron — endpoint protetto da token che esegue la routine di importazione condivisa su richiesta.
5. Segnale di aggiornamento della licenza — endpoint di solo segnale che la piattaforma API di ADP Car Market Hub chiama in modo che il plugin esegua nuovamente il pull del suo stato autorevole di licenza / diritti sulle funzionalità.

L'URL di base completo di qualsiasi endpoint è la radice REST di WordPress seguita dalla rotta. Su un sito tipico questo corrisponde a https://example.com/wp-json/as24ci/v1/....

Requisiti o prerequisiti

• WordPress con la REST API abilitata (impostazione predefinita di WordPress).
• Permalink personalizzati per URL REST in stile percorso. Con i permalink semplici gli endpoint sono comunque raggiungibili tramite ?rest_route=.
• Per gli endpoint pubblici dei veicoli: l'opzione as24ci_rest_api_enabled deve essere impostata su 1. Fino ad allora le rotte non vengono registrate e qualsiasi richiesta restituisce un errore 404 da WordPress.
• Per l'endpoint di importazione tramite cron: deve essere generato un cron token nella scheda amministrativa Importazione e limiti.

Riferimento degli endpoint

GET /as24ci/v1/vehicles

Restituisce un elenco paginato e filtrabile dei veicoli importati il cui stato del post CPT è publish.

• Autenticazione: nessuna (pubblico). La rotta viene registrata solo quando as24ci_rest_api_enabled è uguale a 1.
• Parametri di query:
• page — intero ≥ 1. Predefinito 1.
• per_page — intero compreso tra 1 e 100. Predefinito 10.
• make, model — corrispondenza esatta con le chiavi meta corrispondenti.
• fuel_type — corrispondenza LIKE con la chiave meta del tipo di carburante mappata.
• year_min, year_max — intervallo numerico rispetto a _as24ci_year.
• price_min, price_max — intervallo numerico rispetto a _as24ci_price.
• orderby — uno tra date, price, mileage, title. Predefinito date.
• order — asc o desc (case-insensitive). Predefinito desc.
• Formato della risposta: ``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 } ``
• Note: Il campo image è la dimensione medio-grande di WordPress dell'immagine in evidenza (stringa vuota se non esiste una miniatura). Il campo currency utilizza come fallback il valore dell'opzione as24ci_default_currency quando non è memorizzata alcuna valuta specifica per il veicolo.

GET /as24ci/v1/vehicles/<id>

Restituisce i dettagli completi di un singolo veicolo.

• Autenticazione: nessuna (pubblico). Stesse restrizioni dell'endpoint di elenco.
• Parametro di percorso: id — intero positivo. Validato e convertito in absint.
• Risposta: Tutti i campi della risposta di elenco più:
• description — utilizza il riassunto di WordPress se presente, altrimenti il contenuto del post troncato (≈55 parole).
• images — array di URL degli allegati alla dimensione large, che unisce le immagini della galleria manuale (_as24ci_manual_image_ids) e le immagini importate (_as24ci_image_ids); utilizza come fallback l'immagine in evidenza quando entrambe sono vuote.
• equipment_standard, equipment_optional — array di stringhe.
• seller — nome visualizzato del concessionario.
• Errori:
• 404 (as24ci_vehicle_not_found) quando il post non esiste, non è il CPT as24ci_car o non è pubblicato.

POST /as24ci/v1/favorites

Utilizzato dalla pagina dei preferiti del frontend per recuperare i dati di riepilogo dei veicoli per gli ID che il visitatore ha memorizzato nella memoria locale del browser.

• Autenticazione: nessuna (pubblico). Sempre registrato.
• Corpo della richiesta: oggetto JSON con ids, un array di ID dei post. Validato per essere un array; sanificato in un elenco univoco di interi positivi. Vengono elaborati fino a 50 ID per chiamata.
• Risposta: { "vehicles": [ ... ] }.
• Note: L'endpoint legge solo i veicoli pubblicati. I post a cui il visitatore non ha più accesso (eliminati, bozze, tipo di post errato) vengono omessi silenziosamente.

POST /as24ci/v1/analytics/track

Riceve eventi di visualizzazione, visualizzazione archivio, visualizzazione confronto, visualizzazione preferiti, ricerca filtri, apertura contatto e invio lead dal pixel di tracciamento di analytics.

• Autenticazione: nessuna (pubblico). Sempre registrato.
• Parametri nel corpo della richiesta:
• post_id — intero ≥ 0. Predefinito 0.
• event_type — deve essere uno dei nomi di evento consentiti: view, view_archive, view_compare, view_favorites, filter_search, contact_open, lead_sent.
• extra_data — stringa sanificata opzionale. Per filter_search, la stringa deve essere un oggetto JSON contenente le coppie chiave/valore dei filtri attivi; il server applica la stessa logica di minimizzazione utilizzata dal tracciamento PHP diretto prima di salvare.
• Risposta: { "tracked": true } in caso di successo, { "tracked": false } con HTTP 400 quando l'evento richiede un post di un veicolo che non esiste o non è pubblicato.
• Note: Questo endpoint è intenzionalmente permissivo in modo che i visitatori anonimi possano inviare eventi di analytics. Non fare affidamento su di esso per dati aziendali autorevoli; consultare la guida Tracciamento di Analytics per le note sulla conservazione e sulla privacy.

GET /as24ci/v1/cron-import

Endpoint protetto da token che esegue la routine di importazione condivisa. Esso delega allo stesso metodo Scheduler::run_import() utilizzato dal hook WP-Cron e dal pulsante di amministrazione Avvia ora.

• Autenticazione: bearer token. Fornire il token tramite l'intestazione HTTP Authorization: Bearer <token> (scelta consigliata — mantiene il token fuori dai log di accesso) o tramite il parametro di query ?token=<token>.
• Memorizzazione del token: persistito nell'opzione as24ci_cron_token. Generarlo o ruotarlo da Importazione e limiti nell'amministrazione del plugin.
• Risposte:
• 403 quando non è configurato alcun token o il token fornito non corrisponde.
• 200 con { "success": true, "message": "...", "counts": { ... } } in caso di esecuzione riuscita.
• 429 con success: false quando un'altra importazione è già in corso e l'esecutore ha rifiutato di avviarne una seconda.
• 500 quando l'esecutore ha generato un'eccezione.
• Effetto collaterale: un'autenticazione riuscita aggiorna l'opzione as24ci_last_external_cron_run, che viene utilizzata dalla scheda Sistema e aiuto per confermare che il cron esterno sta raggiungendo il sito.

POST /as24ci/v1/license-refresh-signal

Endpoint di solo segnale che la piattaforma API di ADP Car Market Hub chiama dopo una modifica della licenza o dei diritti sulle funzionalità in modo che il plugin esegua immediatamente il pull del suo stato autorevole. Di proprietà di AS24CI\License_Refresh_Signal e registrato incondizionatamente (come /cron-import), indipendentemente da as24ci_rest_api_enabled.

• Autenticazione: gestita all'interno della callback utilizzando un modello di fiducia basato solo sul segnale. Nulla del corpo della richiesta viene considerato attendibile come dato; la richiesta attiva solo License_Manager::refresh(). Il gestore impone, nell'ordine: POST + tipo di contenuto JSON; un product_key corrispondente (rispetto a License_Client::PRODUCT_KEY); un installation_uid corrispondente quando entrambe le parti ne hanno uno; una licenza locale configurata; un segreto del segnale di aggiornamento fornito per installazione; un timestamp recente nell'intestazione e un nonce non utilizzato (protezione da replay, finestra di 5 minuti); e una firma HMAC-SHA256 sul timestamp + corpo grezzo.
• Limitazione della frequenza (Rate limiting): i segnali ripetuti entro una finestra di 30 secondi vengono accettati ma non aggiornati e ricevono come risposta 429 in modo che una raffica di richieste non possa mai sovraccaricare la piattaforma API.
• Risposte: 200 su un aggiornamento attivato; 4xx/503 per i fallimenti di validazione sopra indicati (403 mancata corrispondenza prodotto/installazione, 409 senza licenza / nonce riutilizzato, 401 timestamp/firma errati, 503 quando non è configurato alcun segreto del segnale).

Note operative

• Gli endpoint pubblici dei veicoli eseguono chiamate standard WP_Query e rispettano la normale memorizzazione nella cache degli oggetti di WordPress. Richieste identiche ripetute beneficiano delle cache dei post e dei post-meta.
• I filtri numerici (year_min/year_max, price_min/price_max) vengono aggiunti a una meta_query. Su cataloghi di grandi dimensioni, assicurarsi che le chiavi meta sottostanti siano indicizzate a livello di database se si prevede un traffico intenso. Verificare l'esatta strategia di indicizzazione nella versione corrente del plugin prima della pubblicazione.
• L'endpoint di elenco applica update_postmeta_cache() per i post restituiti per mantenere prevedibili i tempi di risposta.
• L'endpoint dei preferiti limita rigidamente ogni richiesta a 50 ID per prevenire abusi e mantenere ragionevoli i payload di risposta.
• L'endpoint di importazione tramite cron imposta nocache_headers() in modo che i proxy di memorizzazione nella cache non interferiscano con le esecuzioni pianificate.
• Il confronto dei token utilizza hash_equals() per mitigare gli attacchi di temporizzazione (timing attacks). Ciononostante, preferire l'intestazione Authorization: Bearer per evitare di esporre il token tramite intestazioni referrer, cronologia del browser o log di accesso del server web.

Riferimento della configurazione

Per l'elenco completo delle opzioni del plugin, consultare la guida Memorizzazione di opzioni e impostazioni.

Risoluzione dei problemi

• /vehicles restituisce 404 — l'API pubblica è disabilitata. Impostare as24ci_rest_api_enabled su '1' in Importazione e limiti (o tramite WP-CLI / update_option).
• /cron-import restituisce 403 — non è ancora stato configurato alcun token, oppure il valore fornito non corrisponde. Generare un nuovo token dall'amministrazione e riprovare.
• /cron-import restituisce 429 — un'altra importazione è già in corso e un blocco impedisce una seconda esecuzione simultanea. Attendere che l'esecuzione corrente termini; consultare la guida Eventi cron e pianificatore per il TTL del blocco.
• Array vehicles vuoto sull'endpoint di elenco senza filtri — nessun veicolo è pubblicato o il catalogo non è stato ancora importato. Controllare la scheda Importazione e limiti e i log di importazione.
• HTTP 400 imprevisto su /analytics/track — l'evento richiede un post di un veicolo pubblicato ma post_id fa riferimento a un post in bozza, eliminato o non relativo a un veicolo.

Documenti correlati

• Azioni AJAX
• Webhook
• Eventi cron e pianificatore
• Memorizzazione di opzioni e impostazioni
• Tracciamento di Analytics
• Sicurezza e permessi