Documentazione · Guida all'integrazione

Configurazione delle API di AutoScout24

Questo documento spiega come l'accesso alle API di AutoScout24 si integra nel plugin ADP Car Market Hub, quali credenziali sono necessarie al plugin e come un amministratore può verificare che l'account del concessionario sia raggiungibile dal sito WordPress.

L'attenzione qui è rivolta al lato integrazione del lavoro — la relazione tra il plugin, l'account AutoScout24 del concessionario e le persone che forniscono l'accesso alle API. Per la guida dettagliata campo per campo della pagina delle impostazioni, consulta Configurazione delle credenziali API.

Quando utilizzare questo documento

Utilizza questo documento se stai:

Pianificando una nuova integrazione del plugin con l'accesso API AutoScout24 di un concessionario.
Verificando che un concessionario disponga effettivamente del tipo di accesso API richiesto dal plugin prima di iniziare la configurazione di WordPress.
Coordinandoti con un partner di integrazione o con il contatto IT del concessionario per ottenere o ruotare i valori di accesso alle API.
Verificando, dopo la configurazione, che il sito WordPress possa raggiungere l'API di AutoScout24.

Il pubblico di riferimento è un amministratore o integratore di WordPress che lavora insieme a chi gestisce l'accesso alle API AutoScout24 del concessionario. AD Promotion non rilascia accessi alle API di AutoScout24; le credenziali provengono sempre dall'account del concessionario stesso o dal partner che fornisce l'accesso per conto del concessionario.

Panoramica

ADP Car Market Hub è sviluppato attorno all'API ufficiale di AutoScout24. Il plugin si autentica con un flusso OAuth2 client credentials verso un host API configurato dall'amministratore, richiede un token di accesso e quindi chiama gli endpoint degli annunci per importare i veicoli nel custom post type as24ci_car.

In pratica, l'integrazione coinvolge tre parti indipendenti:

Il concessionario. Possiede l'account AutoScout24 e i dati degli annunci del concessionario.
Il provider API. AutoScout24, o un partner di integrazione che espone i dati di AutoScout24 tramite un gateway equivalente. Questa parte rilascia l'URL di base dell'API, i Seller ID e il Client ID / Client Secret di OAuth.
Il sito WordPress. Contiene la configurazione del plugin, memorizza le credenziali nella tabella delle opzioni di WordPress ed esegue le importazioni periodiche.

Il plugin utilizza esattamente l'host API e le credenziali configurate — non esiste un host AutoScout24 predefinito all'interno del plugin. Ciò consente di puntare la stessa installazione del plugin verso ambienti diversi (ad esempio una sandbox per i test e l'API di produzione per il sito live) semplicemente modificando la configurazione.

Requisiti preliminari

Prima di configurare la connessione API del plugin, conferma quanto segue:

Il concessionario dispone dell'accesso API a AutoScout24 (o a un gateway di integrazione equivalente) per i Seller ID che devono essere importati. Il login standard del sito web del concessionario AutoScout24 non è una credenziale API e non può essere utilizzato dal plugin.
Hai ricevuto, tramite un canale sicuro, i valori necessari al plugin:
URL di base dell'API – l'URL HTTPS completo dell'ambiente AutoScout24 o del gateway del partner.
Seller ID (uno o più) – gli identificativi stabili dell'account rilasciati dal provider API. Il Seller ID non corrisponde al nome visualizzato del concessionario sul sito web di AutoScout24.
Client ID – l'identificativo del client OAuth.
Client Secret – la chiave segreta del client OAuth associata al Client ID.
Il sito WordPress soddisfa i requisiti di hosting, PHP e database e i requisiti di API, rete e SSL. Le connessioni HTTPS in uscita verso l'host API devono essere consentite.
È disponibile un account amministratore sul sito WordPress.

Se uno qualsiasi di questi valori è sconosciuto, non inventarlo. Contatta la parte che ha fornito l'accesso API al concessionario e richiedili tramite un canale sicuro.

Istruzioni passo dopo passo

La guida dettagliata dell'interfaccia utente delle impostazioni si trova in Configurazione delle credenziali API. Il flusso di integrazione ad alto livello è il seguente:

Conferma l'accesso API con il provider. Verifica che l'accesso API del concessionario sia attivo, che la coppia Client ID / Client Secret sia valida e che le credenziali siano autorizzate per ogni Seller ID che deve essere importato. Le concessionarie multi-sede in genere richiedono un'autorizzazione esplicita per ciascun Seller ID.
Ricevi i valori in modo sicuro. Utilizza un gestore di password, un messaggio crittografato o un altro metodo sicuro di trasferimento file. Non accettare credenziali tramite email semplice o chat.
Configura il plugin. In WordPress, apri Car Market Hub → Settings e inserisci l'URL di base dell'API, il Seller ID, il Client ID e il Client Secret nella scheda API Connection & General Settings.
Esegui il test di connessione. Apri Car Market Hub → Tools ed esegui il test di connessione API come descritto in Test di connessione. Non avviare l'importazione dei veicoli finché il test non ha esito positivo.
Esegui prima un'importazione ridotta. Utilizza il Batch-Wizard o una singola esecuzione pianificata con un limite di veicoli basso prima di abilitare l'automazione completa. Questo convalida il comportamento end-to-end senza importare l'intero catalogo al primo tentativo.
Abilita le importazioni pianificate. Una volta verificato il funzionamento dell'importazione manuale, abilita WP-Cron o configura un trigger cron a livello di server. Vedi Configurazione del Cron del server.

Se qualcosa non funziona lungo il percorso, consulta Errori di connessione API prima di modificare la configurazione.

Riferimento di configurazione

Il plugin espone solo i campi necessari per comunicare con l'ambiente AutoScout24 configurato. Le etichette sottostanti corrispondono a quelle presenti in Car Market Hub → Settings.

Campo	Scopo	Origine
API Base URL	URL HTTPS completo dell'ambiente AutoScout24 o del gateway del partner. Il plugin utilizza questo URL esattamente come configurato.	Fornito da AutoScout24 o dal partner di integrazione.
Seller ID	Uno o più identificativi dell'account del concessionario. Più Seller ID vanno inseriti separati da virgola.	Fornito insieme all'accesso API. Non corrisponde al nome visualizzato del concessionario sul sito web di AutoScout24.
Client ID	Identificativo del client OAuth. Trattalo come riservato anche se tecnicamente non è segreto.	Rilasciato dal provider API.
Client Secret	Chiave segreta del client OAuth. Memorizzata nella tabella delle opzioni di WordPress; trattala come una credenziale sensibile.	Rilasciata dal provider API. Se smarrita, normalmente deve essere riemessa — non può essere recuperata.
Default currency	Utilizzata quando un annuncio importato non fornisce un valore di valuta. Non è una credenziale.	Scelta dall'amministratore in base al mercato del concessionario.

Il plugin ricava automaticamente l'endpoint del token OAuth e il token audience dall'URL di base dell'API configurato; non esiste un campo separato nell'interfaccia utente per questi valori. Se il provider API richiede valori non standard, contatta AD Promotion o il partner di integrazione prima di modificare qualsiasi cosa — la derivazione standard è quella prevista dalla maggior parte degli ambienti.

Note operative

Archiviazione. Le credenziali sono memorizzate come opzioni di WordPress. Chiunque abbia accesso come amministratore di WordPress, accesso al file system del database o accesso a un backup del database può leggerle. Applica le stesse protezioni utilizzate per qualsiasi altro segreto gestito dalla tua organizzazione.
Caching dei token. Il plugin richiede un token di accesso OAuth prima della sua prima chiamata API e lo memorizza nella cache. Le importazioni successive riutilizzano il token memorizzato nella cache fino alla sua scadenza. Dopo aver ruotato le credenziali, è buona norma svuotare la cache dei token da Car Market Hub → Tools in modo che la richiesta successiva utilizzi immediatamente le nuove credenziali.
Installazioni multi-ambiente. Il plugin non ha un interruttore integrato per produzione / sandbox. Cambiare ambiente significa modificare l'URL di base dell'API, il Seller ID, il Client ID e il Client Secret con i valori dell'ambiente di destinazione ed eseguire nuovamente il test di connessione. Utilizza credenziali separate per ciascun ambiente WordPress in modo che le attività di staging non possano interferire accidentalmente con i dati di produzione.
Concessionarie multi-sede. Quando sono configurati diversi Seller ID, tutti vengono interrogati con lo stesso Client ID / Client Secret. Le credenziali devono essere autorizzate per ogni Seller ID presente nell'elenco — altrimenti i singoli venditori falliranno con un errore di autorizzazione durante l'importazione.
Registrazione dei log. Le chiamate API e le richieste di token vengono registrate nella directory dei log del plugin in wp-content/uploads/as24ci-logs/. I log includono dettagli sufficienti per diagnosticare i problemi, ma il Client Secret non viene scritto in testo non crittografato. Tratta la directory dei log come riservata.
Coordinamento con il provider API. Il plugin può fare solo ciò che il provider API consente. Se l'accesso API del concessionario viene sospeso, limitato o ridotto a un sottoinsieme di Seller ID, il plugin segnalerà tali errori ma non potrà aggirarli. Segnala sempre questi problemi alla parte che ha fornito l'accesso.

Convalida dell'accesso all'account

Dopo aver configurato il plugin, convalida l'accesso in questo ordine:

Test di connessione. Esegui il test di connessione API su Car Market Hub → Tools. Un esito positivo conferma che l'URL di base dell'API è raggiungibile, che il flusso OAuth va a buon fine e che il primo Seller ID configurato è riconosciuto dall'API. Vedi Test di connessione.
Importazione manuale di un piccolo lotto. Utilizza il Batch-Wizard per importare un numero ridotto di veicoli. Conferma che gli annunci appaiano sotto Car Market Hub → Cars e che i prezzi, la valuta e gli attributi di base sembrino corretti.
Verifica dell'importazione delle immagini. Conferma che la prima immagine di ciascun veicolo di prova sia stata scaricata e allegata. Se l'elaborazione delle immagini è in coda, controlla lo stato della coda delle immagini su Car Market Hub → Import & Limits.
Scheda System & Help. Esamina gli indicatori diagnostici nella scheda System & Help per confermare che non vi siano avvisi in sospeso relativi alla connettività API, alla pianificazione o all'archiviazione.

Verifica questo flusso di convalida nella versione corrente del plugin prima di pubblicare le istruzioni destinate ai clienti, poiché le etichette dell'interfaccia utente possono evolvere tra una versione e l'altra.

Risoluzione dei problemi

Sintomo	Causa probabile	Cosa verificare
Il test di connessione segnala un errore di autenticazione.	Client ID / Client Secret errati, ambiente non corrispondente o spazi vuoti incollati in un campo delle credenziali.	Reinserisci sia il Client ID che il Client Secret. Conferma con il provider API che i valori siano validi per l'URL di base dell'API configurato.
Il test di connessione segnala "nessun Seller ID configurato".	Il campo Seller ID non è stato salvato o contiene solo spazi vuoti / una virgola di troppo.	Riapri le impostazioni, reinserisci il Seller ID e salva di nuovo.
Il test di connessione fallisce con un errore di rete o SSL.	Le connessioni HTTPS in uscita verso l'host API sono bloccate, il pacchetto CA del server è obsoleto o il DNS non risolve l'host.	Vedi Requisiti di API, rete e SSL e Errori di connessione API.
La connessione funziona ma non viene importato alcun veicolo per uno specifico Seller ID.	Le credenziali non sono autorizzate per quel Seller ID, oppure il venditore non ha annunci pubblicati.	Contatta il provider API per confermare l'autorizzazione. Verifica sull'account AutoScout24 del concessionario che gli annunci siano attivi.
Dopo aver ruotato le credenziali, sembrano essere ancora utilizzate quelle vecchie.	Il token di accesso memorizzato nella cache non è ancora scaduto.	Svuota la cache dei token da Car Market Hub → Tools e ripeti il test di connessione.
L'importazione funziona parzialmente ma alcuni veicoli falliscono ripetutamente.	Problemi con i dati lato provider o limitazione della frequenza (rate limiting) sull'API.	Esamina i log del plugin in `wp-content/uploads/as24ci-logs/` e segnala i fallimenti ripetibili al provider API con i relativi estratti di log (con i dati sensibili oscurati).