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 in produzione.

Quando utilizzare questo documento

Utilizzare questo documento quando si desidera:

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

Panoramica

Il plugin utilizza esclusivamente l'API HTTP standard di WordPress (wp_remote_get / wp_remote_post), che utilizza cURL sotto il cofano, 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 sono HTTPS sulla porta standard 443. Non sono previsti fallback in HTTP semplice.
Autenticazione basata su token. L'API di AutoScout24 utilizza le credenziali client 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 connessioni 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 di immagini di AutoScout24 come classe piuttosto che bloccare 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.
Host API carcuro — richiesto quando si utilizza la sorgente carcuro. HTTPS in uscita verso l'endpoint carcuro per estrarre l'inventario del concessionario con il token aziendale configurato.
Sorgente di feed automatica — richiesta quando si utilizza un feed automatico. A seconda della posizione del feed configurata, si tratta di HTTPS in uscita (URL https:// e link di condivisione cloud come Dropbox/Google Drive/OneDrive/Google Sheets) su TCP/443, oppure FTP / FTPS in uscita (tipicamente TCP/21 più porte dati in modalità passiva) o SFTP (TCP/22) verso il server del feed. Un feed da cartella server / percorso file assoluto non richiede alcun accesso alla rete in uscita. SFTP utilizza l'estensione PHP ssh2 o un wrapper di stream SFTP.
Sorgente di importazione e-mail — richiesta quando si utilizza la sorgente di importazione e-mail. IMAP in uscita verso l'host della casella di posta configurata (tipicamente TCP/993 per IMAPS, o TCP/143 con STARTTLS). Richiede l'estensione PHP imap.

Queste destinazioni specifiche per sorgente sono rilevanti solo quando è configurata la sorgente corrispondente in Universal Import; un sito che importa esclusivamente da AutoScout24 non ha bisogno di nessuna di esse.

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 AutoScout24 e qualsiasi futuro cambio di host OAuth possano essere supportati senza un aggiornamento del codice. La connessione a AutoScout24 — e le credenziali di ogni altra sorgente dati — vengono ora inserite nella pagina centrale Universal Import (as24ci-universal-import); nelle versioni precedenti si trovavano sotto Impostazioni. Il Client Secret e gli altri segreti delle sorgenti sono memorizzati crittografati a riposo. Consultare il Riferimento a importazione e limiti (Universal Import Reference).

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

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

Catena SSL e TLS

Certificati. L'host deve considerare attendibili le catene di certificati servite 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 TLS moderno; i siti bloccati su versioni precedenti falliranno con errori di handshake.
Nessuna eccezione per i 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 di certificato.

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). Sui server protetti con DNS split-horizon o filtrato, assicurarsi che le destinazioni in uscita del plugin vengano risolte dalla rete dell'applicazione, non solo dalla workstation dell'operatore.
Firewall in uscita. Consentire TCP/443 verso le destinazioni sopra elencate. Se il firewall impone una lista di consentiti esplicita di nomi di dominio completi (FQDN), consentire almeno l'host API di AutoScout24 configurato più i nomi host della CDN di 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 l'ambiente di hosting impone un proxy in uscita, configurare queste costanti 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à. Verificare questo aspetto con il proprio account manager di AutoScout24 e riservare un IP di uscita stabile se necessario.
WAF / reverse proxy sul lato WordPress. Assicurarsi che il WAF non rimuova o modifichi 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. Utilizzarli 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 dall'utente come "Missing API Base URL", "Token request failed" o codici di errore HTTP specifici.
Scheda Sistema e Aiuto / Stato. 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 di distribuzione.
Scheda Strumenti → Cancella cache dei token. Invalida il token OAuth memorizzato nella cache in modo che la chiamata successiva ne ottenga uno nuovo. Utilizzare questa opzione subito dopo aver ruotato le credenziali client o 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 decisivi:

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". Configurare Settings → API Base URL (ad es. https://api.autoscout24.ch) e salvare prima di riprovare.
"Missing API credentials (Client ID/Secret)". Incollare le credenziali fornite da AutoScout24 e salvare.
"Token request failed" con HTTP 401/403. Le credenziali sono errate, scadute o l'URL del token/audience non corrisponde a quello per cui AutoScout24 ha emesso le credenziali. Verificare nel portale partner di AutoScout24.
"Token request failed" con HTTP 5xx. Problema temporaneo sul lato AutoScout24. Riprovare 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. Controllare /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 la porta TCP/443 verso la destinazione, oppure è richiesto un proxy upstream (configurare WP_PROXY_* in wp-config.php).
Errore cURL 28 ("Operation timed out"). Latenza di rete o un proxy in uscita che ritarda la connessione. Verificare la raggiungibilità con curl -v dallo stesso server web.
Errore cURL 60 ("SSL certificate problem"). Il bundle CA di sistema è obsoleto o un proxy di intercettazione presenta un certificato non attendibile. Aggiornare ca-certificates (o equivalente) e installare la CA radice aziendale nel trust store di sistema.
Il download delle immagini non riesce anche se gli annunci funzionano. Gli URL delle immagini potrebbero risiedere su host AutoScout24 diversi; ampliare la whitelist in uscita per coprire i 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"). Salvare nuovamente la pagina dei Permalink e riprovare.
Le chiamate cron esterne restituiscono 403 "Invalid or missing token". L'intestazione o il parametro di query non corrisponde al token salvato. Rigenerare il token nella scheda Importazione e limiti e aggiornare 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, o la configurazione Gemini gestita in AS24CI\Ai_Config non è stata predisposta. L'importatore principale non è influenzato.