Riferimento degli endpoint REST

Questa appendice elenca le rotte dell'API REST registrate dal plugin ADP Car Market Hub sotto il namespace as24ci/v1.

Quando utilizzare questo documento

Utilizza questo riferimento quando hai la necessità di chiamare un endpoint del plugin, quando stai diagnosticando risposte 403/404 impreviste o quando stai documentando un'integrazione. Per la descrizione concettuale di ciascun endpoint, consulta REST API Endpoints.

Panoramica

Tutte le rotte registrate dal plugin utilizzano l'API REST di WordPress e condividono il namespace as24ci/v1. L'URL completo di qualsiasi endpoint è la radice REST di WordPress seguita dalla rotta, tipicamente https://example.com/wp-json/as24ci/v1/....

Gli endpoint si dividono in cinque gruppi:

1. Dati pubblici dei veicoli (/vehicles, /vehicles/{id}) — disabilitati per impostazione predefinita; controllati da as24ci_rest_api_enabled.
2. Helper dei preferiti (/favorites) — utilizzato dalla pagina dei preferiti del front-end.
3. Tracciamento degli analytics (/analytics/track) — utilizzato dallo script del front-end.
4. Trigger di importazione cron (/cron-import) — protetto da token; utilizzato da pianificatori esterni.
5. Segnale di aggiornamento della licenza (/license-refresh-signal) — utilizzato dall'API Platform per richiedere al sito di riconvalidare la propria licenza.

Riepilogo degli endpoint

GET /as24ci/v1/vehicles

Elenco paginato e filtrabile dei veicoli importati il cui stato dell'articolo è publish.

Parametri di query:

Risposta (struttura):

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

Il campo image rappresenta la dimensione medio-grande dell'immagine in evidenza (stringa vuota se assente). Il campo currency ripiega su as24ci_default_currency quando non è memorizzata alcuna valuta specifica per il veicolo.

GET /as24ci/v1/vehicles/{id}

Dettagli completi per un singolo veicolo.

• Parametro di percorso: id — intero positivo; validato e convertito tramite absint.
• Autenticazione: nessuna (pubblico). Stesso controllo dell'endpoint dell'elenco.
• Risposta: tutti i campi della risposta dell'elenco più description, images (array di URL degli allegati alla dimensione large, che unisce le immagini manuali e quelle importate e ripiega sull'immagine in evidenza), equipment_standard, equipment_optional e seller.
• Errori: 404 as24ci_vehicle_not_found quando l'articolo non esiste, non è il CPT as24ci_car o non è pubblicato.

POST /as24ci/v1/favorites

Idrata i preferiti del visitatore con i dati correnti dei veicoli per gli ID memorizzati nel local storage del browser.

• Autenticazione: nessuna (pubblico). Sempre registrato.
• Corpo: oggetto JSON con ids — un array di ID degli articoli. Sanificato in un elenco univoco di interi positivi; limitato a un massimo di 50 ID per richiesta.
• Risposta: { "vehicles": [ ... ] }.
• Note: Vengono restituiti solo i veicoli pubblicati. Gli articoli a cui il visitatore non ha più accesso (eliminati, bozze, tipo di articolo errato) vengono omessi silenziosamente.

POST /as24ci/v1/analytics/track

Riceve gli eventi di analytics dal pixel di tracciamento del front-end.

• Autenticazione: nessuna (pubblico). Sempre registrato.
• Parametri del corpo:
• post_id — intero ≥ 0. Predefinito 0.
• event_type — uno tra view, view_archive, view_compare, view_favorites, filter_search, contact_open, lead_sent.
• extra_data — stringa sanificata opzionale. Per filter_search, deve essere un oggetto JSON contenente le coppie chiave/valore dei filtri attivi.
• Risposta: { "tracked": true } in caso di successo, oppure { "tracked": false } con HTTP 400 quando l'evento richiede un articolo di veicolo che non esiste o non è pubblicato.
• Note: Intenzionalmente permissivo in modo che i visitatori anonimi possano inviare eventi. Non fare affidamento su di esso per dati aziendali autorevoli.

GET /as24ci/v1/cron-import

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

• Autenticazione: bearer token. Fornisci il token tramite l'intestazione HTTP Authorization: Bearer <token> (scelta consigliata — evita che il token compaia nei log di accesso) o tramite il parametro di query ?token=<token>. Il confronto utilizza hash_equals() per mitigare gli attacchi di temporizzazione (timing attacks).
• Memorizzazione del token: opzione as24ci_cron_token. Generalo o ruotalo 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 as24ci_last_external_cron_run, che la scheda Sistema e aiuto utilizza per confermare che il cron esterno sta raggiungendo il sito. La visita a qualsiasi URL con ?as24ci_cron=1 aggiorna anche questo timestamp tramite l'hook heartbeat su init.

Esempio di chiamata cron esterna (segnaposto — sostituisci con il tuo host e un token generato):

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 di segnale leggero che consente all'API Platform di richiedere al sito di riconvalidare la propria licenza fuori banda (ad esempio dopo un cambio di piano). Registrato in modo incondizionato affinché la piattaforma possa sempre raggiungerlo; non è vincolato dall'opzione dell'API REST pubblica dei veicoli.

• Autenticazione: modello di attendibilità basato solo sul segnale. L'autenticazione viene gestita all'interno della callback anziché da un permission_callback; la richiesta deve essere in formato JSON e viene validata rispetto alla struttura del segnale prevista.
• Corpo: oggetto JSON. I campi di correlazione sicuri e non segreti (request_id, event) vengono restituiti per scopi di tracciamento.
• Risposte:
• 405 method_not_allowed quando la richiesta non è POST.
• 400 invalid_content_type quando il corpo non è in formato JSON, o 400 invalid_json quando non è possibile analizzare il corpo.
• 200 quando il segnale viene accettato.
• Proprietario: AS24CI\License_Refresh_Signal.

Note operative

• Gli endpoint pubblici dei veicoli eseguono chiamate WP_Query standard 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 si aggiungono a un meta_query. Su cataloghi di grandi dimensioni, assicurati che le chiavi meta sottostanti siano indicizzate a livello di database se prevedi un traffico intenso. Verifica la strategia di indicizzazione nella versione corrente del plugin prima della pubblicazione.
• L'endpoint dell'elenco applica update_postmeta_cache() sui post restituiti per mantenere prevedibili i tempi di risposta.
• L'endpoint dei preferiti limita rigidamente ogni richiesta a 50 ID per prevenire abusi.
• L'endpoint di importazione cron imposta nocache_headers() in modo che i proxy di memorizzazione nella cache non interferiscano con le esecuzioni pianificate.
• Si raccomanda l'uso di permalink personalizzati (pretty permalinks) per gli URL REST in stile percorso. Con i permalink semplici, gli endpoint sono comunque raggiungibili tramite ?rest_route=.

Risoluzione dei problemi

• /vehicles restituisce 404. L'API pubblica è disabilitata. Imposta as24ci_rest_api_enabled su '1' in Impostazioni → SEO e integrazioni (o tramite WP-CLI / update_option).
• /cron-import restituisce 403. Non è configurato alcun token (as24ci_cron_token vuoto — il messaggio di risposta lo conferma) oppure il token fornito non corrisponde. Genera un nuovo token dall'amministrazione e riprova.
• /cron-import restituisce 429. Un'altra importazione è già in corso e un blocco impedisce una seconda esecuzione simultanea. Attendi il completamento dell'esecuzione corrente.
• Array vehicles vuoto sull'endpoint dell'elenco senza filtri. Nessun veicolo è pubblicato o il catalogo non è stato ancora importato. Controlla la schermata Importazione e limiti e i log di importazione.
• HTTP 400 su /analytics/track. L'evento richiede un articolo di veicolo pubblicato, ma post_id fa riferimento a una bozza, a un articolo eliminato o a un articolo che non è un veicolo.

Documenti correlati

• REST API Endpoints
• REST API For Developers
• Cron Hook Reference
• Webhook Event Reference
• Settings Reference