Documentazione · Guida all'integrazione

Credenziali API esterne

Questo documento spiega come gestire in sicurezza le credenziali API esterne utilizzate dal plugin ADP Car Market Hub. Copre la provenienza abituale delle credenziali, cosa non deve mai essere pubblicato, come coordinare i valori con i provider che li emettono e come condividere le informazioni per il supporto senza esporre dati sensibili.

È scritto per qualsiasi amministratore, integratore o partner che gestisce i valori delle credenziali per conto di un rivenditore.

Quando utilizzare questo documento

Utilizza questo documento quando devi:

Ricevere le credenziali da un provider per la prima volta e hai bisogno di sapere come memorizzarle e trasmetterle in sicurezza.
Coordinare la rotazione delle credenziali tra il rivenditore, il provider API e il sito WordPress.
Preparare una richiesta di supporto, uno screenshot o un'esportazione e hai bisogno di sapere cosa oscurare.
Verificare come sono memorizzate le credenziali su un'installazione WordPress.

Panoramica

Il plugin può contenere credenziali per diverse integrazioni indipendenti. L'insieme esatto dipende da quali funzionalità sono abilitate, ma gli esempi tipici includono:

API di AutoScout24 – il Client ID OAuth, il Client Secret e il/i Seller ID utilizzati dall'importatore. Vedi Configurazione delle API di AutoScout24.
AI Assistant – utilizza la configurazione gestita di Google Gemini in ADP Car Market Hub. La chiave API Gemini gestita viene fornita da AD Promotion in AS24CI\Ai_Config dopo l'installazione; non è necessario inserire alcun provider AI, modello o chiave API nel backend di WordPress, e nessuna chiave AI viene memorizzata come opzione di WordPress.
Token cron – un token generato casualmente utilizzato per autenticare l'endpoint cron REST del plugin quando un cron del server esterno avvia le importazioni. Vedi Configurazione del cron del server.
Segreto del webhook – un segreto condiviso utilizzato per firmare i payload dei webhook in uscita con HMAC-SHA256. Vedi Integrazione dei webhook.

Tutti questi valori sono memorizzati come opzioni di WordPress sul sito che esegue il plugin. Non sono mai inclusi nel plugin stesso e devono sempre essere forniti dal cliente o dal suo partner di integrazione.

Da dove provengono normalmente i valori

Credenziale	Emessa da	Note
Client ID / Client Secret di AutoScout24	AutoScout24 o il partner di integrazione che fornisce l'accesso API per il rivenditore.	AD Promotion non emette queste credenziali. Il login del sito web del rivenditore non è una credenziale API.
Seller ID di AutoScout24	AutoScout24 o il partner di integrazione.	Il Seller ID è un identificativo stabile dell'account, non il nome visualizzato del rivenditore.
URL di base dell'API	AutoScout24 o il partner di integrazione.	Determina con quale ambiente comunica il plugin. Non esiste un host hardcoded all'interno del plugin.
AI Assistant (Gemini gestito)	Fornito da AD Promotion come parte della configurazione AI gestita.	Memorizzato come costante PHP in `AS24CI\Ai_Config`, non in `wp_options`, e mai esposto nel backend di WordPress. Il cliente non inserisce alcun provider AI, modello o chiave API.
Token cron	Generato automaticamente dal plugin e mostrato nella scheda Importazione e limiti.	Chiunque conosca il token può avviare un'importazione. Trattalo come un segreto.
Segreto del webhook	Definito dal rivenditore o dall'operatore del sistema ricevente; copiato nel plugin e nel ricevitore.	Opzionale. Senza di esso, le firme dei payload non vengono generate.

Se un valore è sconosciuto, non inventarlo. Richiedilo alla parte che possiede il sistema corrispondente.

Cosa non deve essere pubblicato

I seguenti valori non devono mai apparire in alcun luogo pubblico (repository Git pubblici, commenti di ticket pubblici, screenshot incorporati in materiale di marketing, post di blog, assistenti AI senza garanzie di riservatezza, canali di chat pubblici o documenti condivisi accessibili al di fuori del rivenditore / agenzia):

Il Client Secret di AutoScout24 e qualsiasi altro segreto OAuth.
Il token cron del plugin (chiunque disponga del token può avviare importazioni).
Il segreto del webhook.
URL di richiesta completi che includono già un parametro di query ?token=....
Backup del database, esportazioni di wp_options o esportazioni diagnostiche complete del plugin senza previa rimozione dei dati sensibili.
Nomi host interni, endpoint privati o URL non pubblici che fanno parte dell'integrazione.
Dati personali di lead, personale del rivenditore o clienti.

Il Client ID di AutoScout24, il Seller ID e l'URL di base dell'API non sono tecnicamente segreti nello stesso senso di un Client Secret, ma identificano l'account del rivenditore e dovrebbero comunque essere trattati come riservati e condivisi solo con persone che ne hanno legittimamente bisogno.

Regole per una gestione sicura

Utilizza un canale sicuro. Ricevi e trasmetti le credenziali tramite un password manager, un messaggio crittografato end-to-end o uno strumento di trasferimento file sicuro. Le email in chiaro e le chat non crittografate non sono accettabili.
Limita chi le conosce. Solo le persone che configurano o gestiscono effettivamente l'integrazione hanno bisogno dei valori. Rimuovi l'accesso quando le persone lasciano il progetto.
Conserva una copia master al di fuori di WordPress. Il gestore di password centrale del rivenditore è la fonte di verità. L'installazione di WordPress è solo un consumatore delle credenziali.
Ruota dopo l'esposizione. Se una credenziale trapela, richiedi immediatamente una rotazione alla parte emittente, quindi aggiorna il valore nel plugin ed esegui nuovamente il Test di connessione. Per il token cron, rigeneralo dalla scheda Importazione e limiti. Per il segreto del webhook, modificalo sia nel plugin che nel sistema ricevente.
Ruota quando cambiano gli accessi. Quando una persona che ha gestito le credenziali non ha più bisogno dell'accesso (ad esempio, un dipendente lascia la concessionaria o l'agenzia), ruota le credenziali interessate. La rimozione del suo account WordPress non invalida i valori che potrebbe aver copiato in precedenza.
Non salvare le credenziali nel codice. Non inserire mai le credenziali in Git, in un tema, in un mu-plugin o in qualsiasi altro file che finisce nel controllo versione.
Fai attenzione al tipo di campo. Il plugin mostra il Client Secret di AutoScout24 come un campo di input password che intenzionalmente non viene precompilato con il valore esistente al ricaricamento della pagina. Reinserisci il valore solo quando desideri effettivamente modificarlo. Anche il token cron viene mostrato con un controllo Mostra / Nascondi: lascialo nascosto quando condividi screenshot.

Coordinamento delle credenziali con i provider di integrazione

Per qualsiasi integrazione, segui questo schema di coordinamento:

Richiedi l'accesso tramite il rivenditore. Il rivenditore è il titolare dell'account. La fornitura richiede normalmente una richiesta da parte del rivenditore, anche quando un'agenzia o un partner gestisce il lavoro tecnico.
Concorda l'ambiente. Conferma con il provider per quale URL di base dell'API sono valide le credenziali. Mescolare valori di ambienti diversi è la causa più comune di errori di autenticazione.
Conferma l'ambito di autorizzazione. Per AutoScout24, conferma che la coppia Client ID / Client Secret sia autorizzata per ogni Seller ID che deve essere importato. Le concessionarie multi-venditore richiedono spesso un'autorizzazione esplicita per singolo venditore.
Ricevi i valori in modo sicuro. Vedi le Regole per una gestione sicura sopra.
Configura e testa sul sito WordPress. Utilizza la Configurazione delle credenziali API e il Test di connessione prima di abilitare le importazioni automatiche.
Documenta chi possiede cosa. Registra, nella documentazione interna del rivenditore, chi è il contatto presso il provider API, chi ha emesso i valori e quando, e dove è memorizzata la copia master delle credenziali.
Pianifica la rotazione. Concorda un processo per la rotazione delle credenziali, sia a cadenza regolare che su richiesta (dopo una fuga di notizie, dopo cambi di personale, dopo un incidente grave).

Per l'AI Assistant, la configurazione gestita di Google Gemini in AS24CI\Ai_Config è la fonte di verità. Il cliente non configura, memorizza o ruota una chiave API del provider AI nel backend di WordPress; AD Promotion gestisce la fornitura di Gemini gestito.

Condividere informazioni per il supporto senza far trapelare segreti

Quando hai bisogno di condividere informazioni di configurazione o di log con AD Promotion o con un altro contatto di supporto:

Utilizza le informazioni di supporto descritte nella Lista di controllo per le informazioni di supporto.
Oscura i segreti prima della condivisione. Come minimo, sostituisci il Client Secret di AutoScout24, il token cron e il segreto del webhook con [REDACTED].
Per gli URL che includono un parametro di query ?token=..., sostituisci il token con [REDACTED] prima di incollare l'URL in un ticket.
Ritaglia o sfoca le sezioni pertinenti di qualsiasi screenshot che potrebbe rivelare segreti.
La directory dei log del plugin in wp-content/uploads/as24ci-logs/ non scrive il Client Secret in chiaro, ma può includere URL e metadati delle richieste. Tratta la directory dei log come riservata e controlla gli estratti prima di condividerli.

Memorizzazione sul sito WordPress

Credenziali e segreti sono memorizzati come opzioni standard di WordPress. Possono essere letti da qualsiasi codice con accesso al database sullo stesso sito (altri plugin, temi, mu-plugins, processi a livello di server).
I backup del database, le esportazioni di wp_options e gli snapshot completi del server contengono quindi le credenziali. Applica le stesse protezioni previste per qualsiasi altro backup che contiene segreti.
Il plugin non trasmette le credenziali a AD Promotion o a terze parti diverse dal provider API a cui sono destinate le credenziali. Le credenziali di AutoScout24 vengono inviate solo all'URL di base dell'API configurato. I prompt dell'IA vanno all'endpoint gestito di Google Gemini configurato da AD Promotion in AS24CI\Ai_Config.
Per i dettagli su ciò che il plugin memorizza nel database, vedi la Panoramica sulla memorizzazione dei dati e il Riferimento a database e memorizzazione.

Note operative

Credenziali per ambiente. Utilizza credenziali distinte per ogni ambiente (produzione, staging, locale). Non puntare un sito di staging WordPress alle credenziali di produzione di AutoScout24 a meno che tu non l'abbia concordato esplicitamente con il rivenditore; in caso contrario, l'attività di staging può inquinare le statistiche, attivare email di lead o generare chiamate webhook indesiderate.
Migrazione tra ambienti. Quando copi un database da produzione a staging (o viceversa), controlla ogni campo delle credenziali sul sito di destinazione. Vedi Migrazione da staging a live.
Disinstallazione. Quando il plugin viene disinstallato con l'opzione Elimina i dati all'attivazione della disinstallazione abilitata, le opzioni memorizzate, comprese le credenziali, vengono rimosse dal database. Se l'opzione è disabilitata, le credenziali rimangono nel database dopo la disinstallazione. Vedi Comportamento di disinstallazione e pulizia.
Verifica il comportamento nella versione corrente. Le etichette specifiche dell'interfaccia utente, i valori predefiniti e le chiavi di memorizzazione esatte possono cambiare tra le versioni. Verifica questo comportamento nella versione corrente del plugin prima di pubblicare istruzioni rivolte ai clienti.

Risoluzione dei problemi

Sintomo	Causa probabile	Cosa verificare
L'autenticazione fallisce immediatamente dopo una modifica delle credenziali.	Un token di accesso preesistente è ancora memorizzato nella cache.	Svuotare la cache dei token da Car Market Hub → Strumenti ed eseguire nuovamente il Test di connessione.
L'autenticazione fallisce sebbene i valori "sembrino corretti".	Spazi vuoti invisibili, virgolette intelligenti o un carattere scambiato (`0` rispetto a `O`, `1` rispetto a `l`).	Incollare prima ogni valore in un editor di testo semplice, rimuovere gli spazi vuoti e poi incollarlo nel campo.
Il plugin segnala che non è configurata alcuna credenziale.	I valori sono stati inseriti ma il modulo non è stato inviato, oppure un plugin di sicurezza ha rimosso la richiesta.	Riaprire la scheda delle impostazioni pertinente e confermare che i valori siano salvati. Disattivare temporaneamente i plugin di sicurezza se interferiscono con l'invio dei moduli di amministrazione.
L'endpoint cron restituisce 403.	Il token cron nell'URL non corrisponde al token memorizzato, oppure il token è stato rigenerato.	Copiare l'attuale URL del trigger REST dalla scheda Importazione e limiti nel cron job del server. Vedere Server Cron Setup.
Il ricevitore webhook rifiuta i payload con una firma non valida.	Il segreto del webhook nel plugin e nel ricevitore non corrisponde più.	Ricopiare il segreto su entrambi i lati e inviare nuovamente un evento di test. Vedere Webhook Integration.
Una credenziale sembra trapelare in un registro o in un ticket.	La redazione era incompleta.	Ruotare immediatamente la credenziale con la parte emittente, quindi aggiornare il plugin e ripetere il test.