Documentazione · Requisiti di sistema

Requisiti di API, rete e SSL

Scopo

ADP Car Market Hub è fondamentalmente un plugin di integrazione: trascorre la maggior parte del suo tempo di esecuzione a comunicare con endpoint HTTPS remoti — l'API di AutoScout24 per veicoli e immagini, l'endpoint gestito di Google Gemini per la generazione opzionale di contenuti tramite intelligenza artificiale e (indirettamente) WordPress.org per gli aggiornamenti del plugin. Questo documento specifica i requisiti di rete in uscita e TLS che il plugin richiede all'host e spiega come convalidarli prima della messa online.

Quando utilizzare questo documento

Utilizza questo documento quando:

Configuri un firewall, una policy di uscita o un proxy in uscita per un ambiente di hosting.
Scegli un URL di base dell'API per il mercato AutoScout24 del concessionario (ad es. .com, .ch, .de, …).
Analizzi errori di connessione o di autenticazione segnalati dall'importatore o dal Test di connessione.
Convalidi la configurazione di TLS, DNS e certificati CA su un nuovo server.
Verifichi quali endpoint di terze parti saranno contattati dal plugin in produzione.

Panoramica

Il plugin utilizza esclusivamente l'API HTTP standard di WordPress (wp_remote_get / wp_remote_post), che sotto la scocca sfrutta cURL, ereditando così la configurazione TLS/CA del sistema e qualsiasi costante impostata in wp-config.php per i trasporti HTTP e i proxy.

Il profilo di rete è:

Solo in uscita. Il plugin non apre mai porte in ingresso oltre a quelle richieste da WordPress stesso. L'attivazione del cron è esposta tramite l'API REST standard di WordPress, che viene già eseguita sul listener HTTPS esistente del sito.
Solo HTTPS. Tutti gli endpoint di terze parti utilizzano HTTPS sulla porta standard 443. Non sono previste alternative in HTTP semplice.
Autenticazione basata su token. L'API di AutoScout24 utilizza le credenziali client di OAuth 2.0. Il plugin richiede un token di accesso dall'URL del token configurato, lo memorizza in un transient fino a poco prima della sua expires_in e lo invia come token bearer nelle richieste successive.
Nessun socket persistente. Ogni richiesta è una chiamata API HTTP di WordPress distinta con un timeout di 30 secondi per le richieste di token; i download delle immagini utilizzano i timeout di download standard di WordPress.

Endpoint in uscita richiesti

L'host deve consentire il traffico HTTPS in uscita (TCP/443) verso le seguenti destinazioni.

Obbligatori

URL di base dell'API di AutoScout24 — configurato in Impostazioni → URL di base dell'API, ad esempio https://api.autoscout24.com (altri mercati utilizzano l'host specifico del paese come api.autoscout24.ch, api.autoscout24.de, ecc.). Utilizzato per i token OAuth, il recupero degli annunci e l'individuazione degli URL delle immagini.
Endpoint del token di AutoScout24 — per impostazione predefinita <base URL>/public/v1/clients/oauth/token. È disponibile un'opzione separata URL del token quando l'endpoint OAuth risiede su un host diverso rispetto alla base dell'API.
Host delle immagini di AutoScout24 — i payload degli annunci restituiscono URL assoluti delle immagini che vengono scaricate direttamente nella libreria multimediale di WordPress. Questi nomi host variano a seconda del mercato e possono cambiare nel tempo, pertanto la policy del firewall dovrebbe consentire le CDN delle immagini di AutoScout24 come classe anziché vincolare un singolo nome host.

Opzionali

https://generativelanguage.googleapis.com — richiesto quando l'AI Assistant è abilitato. Utilizzato per chiamare l'endpoint gestito di Google Gemini configurato in AS24CI\Ai_Config.

Consigliati

https://api.wordpress.org — per i controlli degli aggiornamenti del core, del tema e dei plugin di WordPress.
Il sito stesso del plugin (quando chiamato da un cron esterno) deve essere raggiungibile dallo scheduler che lo attiva.

URL di base dell'API e URL del token

Il plugin rende l'URL di base dell'API e l'URL del token completamente configurabili, in modo che qualsiasi mercato di AutoScout24 e qualsiasi futura modifica dell'host OAuth possano essere supportati senza un aggiornamento del codice.

URL di base dell'API (as24ci_base_url). Obbligatorio. Deve essere lo schema + host (senza barra finale), ad esempio https://api.autoscout24.ch. Il plugin rimuove le barre finali e rifiuta di effettuare chiamate se questo campo è vuoto.
URL del token (as24ci_token_url). Opzionale. Se vuoto, il plugin lo ricava come <base URL>/public/v1/clients/oauth/token. Impostalo esplicitamente solo se AutoScout24 ha fornito un host OAuth diverso per il tuo account.
Audience del token (as24ci_token_audience). Opzionale. Se vuoto, il plugin ricava l'audience dallo schema + host dell'URL di base.
Client ID e Client Secret — credenziali obbligatorie fornite da AutoScout24.
Seller ID — elenco separato da virgole di ID concessionario.

Dopo il salvataggio, l'azione Scheda Strumenti → Test di connessione esegue un recupero reale di OAuth + annunci e segnala un errore chiaro se uno qualsiasi dei parametri sopra indicati è errato.

Catena SSL e TLS

Certificati. L'host deve considerare attendibili le catene di certificati fornite da AutoScout24 (e dall'endpoint gestito di Google Gemini quando le funzionalità AI sono abilitate). Sulle distribuzioni Linux moderne questo avviene automaticamente; su container di lunga durata o immagini isolate, il pacchetto CA (/etc/ssl/certs/ca-certificates.crt su Debian/Ubuntu, /etc/pki/tls/certs/ca-bundle.crt sui sistemi della famiglia RHEL) deve essere mantenuto aggiornato.
Versioni TLS. Il plugin utilizza lo stack OpenSSL/cURL del sistema che, negli ambienti PHP 8.1+ supportati, negozia TLS 1.2 o 1.3 per impostazione predefinita. AutoScout24 richiede un TLS moderno; i siti vincolati a versioni precedenti falliranno con errori di handshake.
Nessuna eccezione per certificati autofirmati. Il plugin non disabilita la verifica dei certificati. I proxy in uscita che eseguono l'intercettazione TLS devono installare la propria CA radice nell'archivio di attendibilità del sistema; in caso contrario, ogni richiesta fallirà con un errore di certificato.
TLS in ingresso. È richiesto un certificato pubblico valido anche sul sito WordPress stesso, sia per la sicurezza generale di WordPress sia per consentire agli scheduler esterni di chiamare l'endpoint REST del cron senza avvisi sui certificati.

DNS, firewall e proxy

DNS. Il processo PHP deve risolvere i nomi host di AutoScout24 (e generativelanguage.googleapis.com quando le funzionalità AI sono abilitate). Su server protetti con DNS split-horizon o filtrato, assicurati che le destinazioni in uscita del plugin vengano risolte dalla rete dell'applicazione, non solo dalla workstation dell'operatore.
Firewall in uscita. Consenti TCP/443 verso le destinazioni sopra elencate. Se il firewall impone una lista di consentiti esplicita di nomi di dominio completi (FQDN), consenti almeno l'host API di AutoScout24 configurato più i nomi host della CDN delle immagini di AutoScout24 presenti nelle risposte dell'API.
Proxy HTTP. WordPress rispetta le costanti standard WP_PROXY_HOST, WP_PROXY_PORT, WP_PROXY_USERNAME, WP_PROXY_PASSWORD e WP_PROXY_BYPASS_HOSTS in wp-config.php. Se il tuo ambiente di hosting impone un proxy in uscita, configurali in modo che le chiamate di wp_remote_* passino attraverso di esso.
Associazione IP di uscita. Alcuni account aziendali di AutoScout24 potrebbero richiedere al concessionario di fornire gli IP di uscita che il plugin utilizzerà. Verifica questo aspetto con il tuo account manager di AutoScout24 e riserva un IP di uscita stabile se necessario.
WAF / reverse proxy sul lato WordPress. Assicurati che il WAF non rimuova o alteri l'intestazione Authorization sull'endpoint REST del cron e non memorizzi nella cache le risposte di /wp-json/as24ci/v1/*.

Test di connessione

Il plugin include diversi strumenti integrati per verificare la rete e il percorso dell'API end-to-end. Utilizzali in questo ordine:

Scheda Strumenti → Test di connessione. Recupera un token OAuth dall'URL del token configurato e quindi chiama l'endpoint degli annunci. Una risposta positiva conferma credenziali, URL di base, audience, DNS, TLS e firewall in uscita in un unico passaggio. I fallimenti restituiscono messaggi leggibili come "Missing API Base URL", "Token request failed" o codici di errore HTTP specifici.
Scheda Stato del sistema e Aiuto / Salute. Mostra l'URL di base configurato, i timestamp dell'ultima esecuzione, la modalità cron e lo stato delle integrazioni opzionali. Utile come dashboard unica prima e dopo le modifiche alla distribuzione.
Scheda Strumenti → Cancella cache dei token. Invalida il token OAuth memorizzato nella cache in modo che la chiamata successiva ne ottenga uno nuovo. Utilizza questa opzione subito dopo aver ruotato le credenziali client o aver modificato l'URL del token.
Scheda Log. Quando il Test di connessione fallisce, l'errore sottostante (ad es. errore cURL 6 "Could not resolve host", errore 28 "Operation timed out", HTTP 401 dall'endpoint del token) viene registrato con un contesto sufficiente per identificare problemi di DNS, firewall, TLS o credenziali.

Per una convalida più approfondita da riga di comando, i seguenti comandi eseguiti dal server web stesso sono solitamente conclusivi:

DNS: getent hosts api.autoscout24.com (o l'host configurato).
Raggiungibilità e catena TLS: curl -v https://api.autoscout24.com/ dovrebbe completare l'handshake TLS senza errori di certificato.
Endpoint del token: curl -v -X POST -d "grant_type=client_credentials" https://<your-token-url> dovrebbe restituire un HTTP 4xx con un corpo di errore strutturato, confermando che l'URL è raggiungibile anche senza credenziali.

Risoluzione dei problemi

"Missing API Base URL". Configura Settings → API Base URL (ad es. https://api.autoscout24.ch) e salva prima di riprovare.
"Missing API credentials (Client ID/Secret)". Incolla le credenziali fornite da AutoScout24 e salva.
"Token request failed" con HTTP 401/403. Le credenziali sono errate, scadute o l'URL/audience del token non corrisponde a quanto emesso da AutoScout24 per tali credenziali. Verifica nel portale partner di AutoScout24.
"Token request failed" con HTTP 5xx. Problema temporaneo lato AutoScout24. Riprova dopo pochi minuti; l'importatore si riprenderà automaticamente alla successiva esecuzione del cron.
Errore cURL 6 ("Could not resolve host"). Il DNS non funziona sul server web. Controlla /etc/resolv.conf, il servizio DNS del provider di hosting e qualsiasi configurazione split-horizon.
Errore cURL 7 ("Failed to connect"). Il firewall in uscita sta bloccando TCP/443 verso la destinazione, oppure è richiesto un proxy a monte (configura WP_PROXY_* in wp-config.php).
Errore cURL 28 ("Operation timed out"). Latenza di rete o un proxy in uscita che ritarda la connessione. Verifica la raggiungibilità con curl -v dal server web stesso.
Errore cURL 60 ("SSL certificate problem"). Il pacchetto CA di sistema è obsoleto o un proxy di intercettazione presenta un certificato non attendibile. Aggiorna ca-certificates (o equivalente) e installa la CA radice aziendale nell'archivio di attendibilità del sistema.
Il download delle immagini fallisce anche se gli annunci funzionano. Gli URL delle immagini potrebbero risiedere su host AutoScout24 diversi; amplia la lista dei consentiti in uscita per coprire le CDN delle immagini di AutoScout24.
Le chiamate cron esterne restituiscono 404 per /wp-json/as24ci/v1/cron-import. I permalink di WordPress devono essere abilitati (qualsiasi impostazione diversa da "Semplice"). Salva nuovamente la pagina dei Permalink e riprova.
Le chiamate cron esterne restituiscono 403 "Invalid or missing token". L'intestazione o il parametro di query non corrisponde al token salvato. Rigenera il token nella scheda Importazione e limiti e aggiorna lo scheduler.
Le chiamate AI falliscono mentre le chiamate AutoScout24 hanno successo. L'host Gemini gestito (generativelanguage.googleapis.com) non è consentito dal firewall in uscita, oppure la configurazione Gemini gestita in AS24CI\Ai_Config non è stata predisposta. L'importatore principale non è influenzato.