Vai al contenuto
Alessandro Matta
Informatica

Come sviluppare un’integrazione tra WordPress e un’API esterna

mattalex 14 min di lettura

Che cos’è un’integrazione API

Un sito WordPress può avere bisogno di comunicare con molti sistemi esterni: gestionali, CRM, software di magazzino, piattaforme di fatturazione, gateway di pagamento, sistemi di prenotazione, servizi di marketing, cataloghi fornitori, applicazioni mobile o piattaforme di intelligenza artificiale.

Quando due sistemi devono scambiarsi dati in modo affidabile, una semplice esportazione manuale non è sempre sufficiente. In questi casi può essere necessario sviluppare una integrazione tra WordPress e un’API esterna.

Un’integrazione ben progettata permette di automatizzare attività ripetitive, ridurre gli errori di inserimento e mantenere coerenti prodotti, ordini, clienti, disponibilità e informazioni aziendali.

Non basta però inviare una richiesta HTTP a un servizio esterno. Una soluzione professionale deve gestire autenticazione, sicurezza, validazione dei dati, errori, log, sincronizzazioni e manutenzione nel tempo.

Un’API, cioè Application Programming Interface, è un insieme di regole che permette a due applicazioni di comunicare tra loro.

Un sistema può esporre endpoint, ovvero indirizzi specifici, attraverso i quali un altro software può:

  • leggere dati;
  • creare nuovi record;
  • aggiornare informazioni esistenti;
  • eliminare dati autorizzati;
  • ricevere notifiche su eventi;
  • avviare processi automatici.

Per esempio, WordPress può inviare un ordine WooCommerce a un gestionale. Il gestionale può restituire un codice di spedizione, aggiornare la disponibilità di un prodotto oppure segnalare che un ordine è stato evaso.

La REST API di WordPress permette alle applicazioni di interagire con il sito inviando e ricevendo dati in formato JSON. Le risorse pubbliche possono essere accessibili senza autenticazione, mentre dati privati, utenti, metadati e contenuti protetti richiedono autorizzazioni adeguate. [223]

Quando serve collegare WordPress a un sistema esterno

Un’integrazione API può essere utile quando il sito deve comunicare con software che fanno parte dei processi aziendali.

Alcuni casi frequenti sono:

  • sincronizzazione tra WooCommerce e un gestionale;
  • aggiornamento di prodotti, prezzi e disponibilità;
  • invio degli ordini a un sistema di magazzino;
  • collegamento con un CRM;
  • recupero di dati da un catalogo fornitori;
  • integrazione con software di fatturazione;
  • invio di contatti a una piattaforma marketing;
  • gestione di prenotazioni da sistemi esterni;
  • collegamento con servizi di spedizione;
  • generazione di contenuti tramite servizi AI;
  • integrazione con app mobile o dashboard aziendali;
  • importazione periodica di file XML, CSV o JSON.

La scelta di sviluppare un’integrazione deve partire da una domanda concreta: quale attività manuale voglio ridurre o eliminare?

Se un operatore deve ogni giorno copiare prodotti, aggiornare quantità, inserire ordini o controllare manualmente dati in più sistemi, un’integrazione può rendere il processo più sicuro e veloce.

Analizzare l’API prima dello sviluppo

Prima di scrivere codice è necessario analizzare la documentazione dell’API esterna.

Non tutte le API offrono le stesse possibilità. Alcune consentono soltanto la lettura dei dati, altre permettono anche creazione, aggiornamento ed eliminazione. Alcune restituiscono dati completi, altre richiedono più chiamate per ottenere informazioni collegate.

Durante l’analisi è importante verificare:

  • base URL dell’API;
  • endpoint disponibili;
  • metodi HTTP supportati;
  • formato dei dati inviati e ricevuti;
  • autenticazione richiesta;
  • limiti di richieste;
  • paginazione dei risultati;
  • codici di risposta;
  • gestione degli errori;
  • webhook disponibili;
  • ambiente sandbox o test;
  • versioni dell’API;
  • politiche di deprecazione.

È utile preparare una mappatura iniziale tra i campi del sistema esterno e quelli di WordPress o WooCommerce.

Per esempio, un prodotto presente in un gestionale potrebbe contenere:

  • codice articolo;
  • nome;
  • descrizione;
  • prezzo;
  • aliquota IVA;
  • quantità;
  • peso;
  • immagine;
  • categoria;
  • stato di disponibilità.

Prima dello sviluppo bisogna decidere in quale campo WooCommerce sarà salvato ciascun dato e quale sistema sarà considerato autorevole.

Definire il flusso dei dati

Una delle decisioni più importanti riguarda la direzione del flusso.

Un’integrazione può essere:

  • unidirezionale, quando i dati vanno soltanto da un sistema all’altro;
  • bidirezionale, quando entrambi i sistemi possono inviare aggiornamenti;
  • event-driven, quando l’aggiornamento avviene dopo un evento;
  • programmata, quando la sincronizzazione avviene a intervalli regolari;
  • manuale assistita, quando un operatore avvia un’importazione dal pannello.

Un esempio unidirezionale può essere il gestionale che aggiorna prodotti e quantità in WooCommerce.

Un esempio bidirezionale può essere:

  • il gestionale invia disponibilità e prezzi a WooCommerce;
  • WooCommerce invia gli ordini al gestionale;
  • il gestionale aggiorna lo stato di evasione o il tracking;
  • WooCommerce mostra al cliente lo stato aggiornato dell’ordine.

La sincronizzazione bidirezionale richiede maggiore attenzione, perché può generare conflitti. Se due sistemi modificano contemporaneamente lo stesso campo, bisogna definire quale valore ha priorità.

API REST, webhook e sincronizzazioni programmate

Le integrazioni tra WordPress e sistemi esterni possono utilizzare più tecniche contemporaneamente.

REST API

Una REST API permette di inviare richieste HTTP a endpoint specifici. Le operazioni più comuni sono:

  • GET per leggere dati;
  • POST per creare dati;
  • PUT o PATCH per aggiornare dati;
  • DELETE per eliminare dati autorizzati.

WordPress mette a disposizione la propria REST API e può anche comunicare con API esterne attraverso funzioni HTTP dedicate.

Webhook

Un webhook è una notifica inviata automaticamente quando avviene un evento.

Per esempio, quando un ordine WooCommerce viene completato, il sito può inviare una richiesta al gestionale. Il gestionale può ricevere il payload, creare l’ordine e restituire una conferma.

I webhook sono utili quando serve un aggiornamento quasi immediato. Devono però essere progettati per gestire errori, ritardi, tentativi multipli e richieste duplicate.

Sincronizzazione programmata

Una sincronizzazione programmata può essere utile quando il sistema esterno non offre webhook oppure quando è necessario riallineare periodicamente i dati.

Per esempio, un processo può recuperare ogni ora:

  • prodotti nuovi;
  • prezzi aggiornati;
  • quantità disponibili;
  • stati degli ordini;
  • documenti o codici tracking.

In molti progetti la soluzione migliore è ibrida: webhook per gli eventi urgenti e sincronizzazione programmata per il controllo generale.

Autenticazione e gestione delle credenziali

Le API possono richiedere chiavi, token, username, password applicative, firme HMAC, OAuth oppure altri sistemi di autenticazione.

Le credenziali devono essere trattate come informazioni riservate.

Non devono essere:

  • inserite direttamente nei template del tema;
  • esposte nel codice JavaScript pubblico;
  • salvate in repository pubblici;
  • registrate nei log;
  • mostrate nel pannello senza protezione;
  • copiate in email o documenti non protetti.

Le credenziali possono essere memorizzate in costanti definite nel file wp-config.php, in variabili d’ambiente oppure in un sistema sicuro di gestione delle configurazioni.

Quando le impostazioni devono essere gestite dal pannello WordPress, è consigliabile utilizzare la Settings API, che permette di definire pagine, sezioni e campi amministrativi con controlli di autorizzazione. [221]

Per la REST API interna di WordPress, le richieste eseguite nel browser da utenti autenticati possono utilizzare cookie e nonce. Per collegamenti tra sistemi esterni possono invece essere usate password applicative o meccanismi di autenticazione specifici, in base al contesto e alla configurazione del sito. [220][226]

Creare un plugin WordPress dedicato

Una integrazione API dovrebbe essere sviluppata, quando possibile, in un plugin WordPress dedicato e non nel file functions.php del tema.

Il tema dovrebbe occuparsi principalmente della presentazione grafica. Un’integrazione con un gestionale, un CRM o un servizio esterno è una funzionalità applicativa che dovrebbe rimanere attiva anche se il tema viene sostituito.

Un plugin dedicato può contenere:

  • pagina impostazioni;
  • gestione delle credenziali;
  • client HTTP;
  • webhook in ingresso;
  • processi pianificati;
  • log;
  • code di elaborazione;
  • mappatura dei dati;
  • strumenti manuali di sincronizzazione;
  • controlli di sicurezza;
  • notifiche di errore;
  • procedure di attivazione e disattivazione.

Questo approccio rende il codice più organizzato, riutilizzabile e semplice da mantenere.

Inviare richieste HTTP da WordPress

WordPress mette a disposizione una HTTP API per comunicare con servizi esterni.

Per recuperare dati da un endpoint è possibile utilizzare:

$response = wp_remote_get(
    'https://api.example.com/v1/products',
    array(
        'timeout' => 20,
        'headers' => array(
            'Authorization' => 'Bearer ' . $token,
            'Accept'        => 'application/json',
        ),
    )
);

La documentazione WordPress indica che wp_remote_get() semplifica il recupero di dati tramite HTTP e permette di definire argomenti come timeout, header, cookie e redirect. [222]

Prima di usare la risposta è necessario verificare se la richiesta ha prodotto un errore:

if ( is_wp_error( $response ) ) {
    $error_message = $response->get_error_message();

    error_log( 'Errore API: ' . $error_message );

    return;
}

È poi possibile controllare il codice HTTP e decodificare il JSON:

$status_code = wp_remote_retrieve_response_code( $response );
$body        = wp_remote_retrieve_body( $response );
$data        = json_decode( $body, true );

if ( 200 !== $status_code || ! is_array( $data ) ) {
    error_log( 'Risposta API non valida' );

    return;
}

Per inviare dati a un endpoint si può utilizzare wp_remote_post():

$response = wp_remote_post(
    'https://api.example.com/v1/orders',
    array(
        'timeout' => 20,
        'headers' => array(
            'Authorization' => 'Bearer ' . $token,
            'Content-Type'  => 'application/json',
            'Accept'        => 'application/json',
        ),
        'body' => wp_json_encode(
            array(
                'order_id' => $order_id,
                'status'   => 'processing',
            )
        ),
    )
);

WordPress raccomanda di usare wp_safe_remote_post() quando l’URL della richiesta è controllato dall’utente, perché applica verifiche aggiuntive sulla sicurezza dell’URL. [225]

Ricevere dati da un sistema esterno

Un sistema esterno può inviare dati a WordPress tramite webhook o endpoint REST personalizzato.

Per esempio, un gestionale può chiamare un endpoint WordPress quando:

  • cambia la disponibilità di un prodotto;
  • viene aggiornato un prezzo;
  • un ordine viene spedito;
  • è disponibile un documento fiscale;
  • un cliente viene aggiornato;
  • si verifica un errore di sincronizzazione.

Un endpoint personalizzato deve essere registrato con attenzione, definendo namespace, route, metodi ammessi e funzione di autorizzazione.

add_action(
    'rest_api_init',
    function () {
        register_rest_route(
            'my-integration/v1',
            '/webhook',
            array(
                'methods'             => 'POST',
                'callback'            => 'my_integration_handle_webhook',
                'permission_callback' => 'my_integration_verify_request',
            )
        );
    }
);

La funzione permission_callback non deve essere lasciata aperta senza controlli. Deve verificare una firma, un token, un header segreto o un altro sistema di autenticazione.

Non utilizzare una callback che restituisce sempre true per endpoint che modificano prodotti, ordini o utenti.

Sincronizzare prodotti, ordini e utenti

Una integrazione tra WordPress e un’API esterna può riguardare diversi tipi di dati.

Prodotti

La sincronizzazione dei prodotti può includere:

  • nome;
  • SKU;
  • descrizione;
  • prezzo;
  • prezzo scontato;
  • quantità disponibile;
  • peso e dimensioni;
  • categorie;
  • attributi;
  • variazioni;
  • immagini;
  • stato di pubblicazione.

Lo SKU o un identificativo esterno stabile è fondamentale per evitare duplicati. Ogni prodotto WooCommerce dovrebbe poter essere collegato a un record preciso del sistema esterno.

Ordini

Un ordine WooCommerce può essere inviato al gestionale insieme a:

  • numero ordine;
  • data;
  • dati cliente;
  • indirizzi di fatturazione e spedizione;
  • prodotti acquistati;
  • quantità;
  • spedizione;
  • tasse;
  • sconti;
  • metodo di pagamento;
  • stato ordine;
  • note cliente.

Il gestionale può poi restituire dati come codice di spedizione, stato di evasione, numero di documento o informazioni di tracking.

Utenti e clienti

La sincronizzazione dei clienti richiede particolare attenzione perché coinvolge dati personali.

È importante definire:

  • quali dati sono realmente necessari;
  • quale sistema è autorevole;
  • come gestire le modifiche;
  • come evitare duplicati;
  • come rispettare le politiche di conservazione;
  • come proteggere i dati durante il trasferimento.

Non è sempre opportuno sincronizzare ogni dato disponibile. Il principio corretto è trasferire soltanto ciò che serve al processo.

Gestire errori, timeout e tentativi

Una richiesta API può fallire per molti motivi:

  • server remoto non raggiungibile;
  • token scaduto;
  • rate limit superato;
  • timeout;
  • errore di validazione;
  • risposta non valida;
  • rete instabile;
  • servizio esterno temporaneamente non disponibile;
  • errore interno del sistema remoto.

Una buona integrazione non deve considerare ogni errore come definitivo. Alcuni problemi sono temporanei e possono essere ritentati.

È utile distinguere tra:

  • errori temporanei, come timeout o risposta 503;
  • errori di autenticazione, che richiedono nuove credenziali;
  • errori di validazione, che richiedono correzione dei dati;
  • errori permanenti, come endpoint non esistente;
  • errori di conflitto, quando il dato è stato modificato altrove.

I tentativi automatici devono essere limitati. Un processo che ripete continuamente una richiesta fallita può aumentare il carico del server e rendere più difficile la diagnosi.

Una strategia utile può prevedere tentativi progressivi: dopo pochi minuti, dopo un’ora e poi dopo alcune ore, con una soglia massima oltre la quale l’errore viene segnalato a un amministratore.

Log, monitoraggio e diagnosi

Un’integrazione senza log è difficile da mantenere.

I log dovrebbero registrare almeno:

  • data e ora della richiesta;
  • tipo di operazione;
  • endpoint chiamato;
  • identificativo del record;
  • codice di risposta HTTP;
  • esito dell’operazione;
  • messaggio di errore;
  • numero di tentativi;
  • tempo di esecuzione.

Nei log non devono essere salvati password, token completi, dati di pagamento o informazioni personali non necessarie.

In WooCommerce può essere utile utilizzare il sistema di log interno per mantenere i messaggi consultabili nell’area amministrativa:

$logger  = wc_get_logger();
$context = array( 'source' => 'my-custom-integration' );

$logger->info(
    'Sincronizzazione completata per il prodotto ID: ' . $product_id,
    $context
);

Per gli errori:

$logger->error(
    'Errore durante la sincronizzazione: ' . $error_message,
    $context
);

Il monitoraggio dovrebbe segnalare anche situazioni come:

  • molti errori consecutivi;
  • azioni pianificate bloccate;
  • ordini non sincronizzati;
  • prodotti senza SKU;
  • token prossimi alla scadenza;
  • tempi di risposta troppo elevati;
  • webhook non ricevuti.

Sicurezza dell’integrazione

Un’integrazione API può diventare un punto di accesso critico. Deve quindi essere protetta come una parte importante dell’infrastruttura del sito.

Le principali misure comprendono:

  • utilizzare sempre HTTPS;
  • verificare token, firme o secret;
  • assegnare soltanto i permessi necessari;
  • limitare gli endpoint pubblici;
  • validare tutti i dati in ingresso;
  • sanitizzare i dati prima del salvataggio;
  • eseguire escaping dell’output;
  • proteggere le credenziali;
  • non esporre dati sensibili nei log;
  • implementare rate limit quando necessario;
  • controllare gli indirizzi IP se il servizio lo consente;
  • ruotare periodicamente chiavi e token;
  • rimuovere credenziali non più utilizzate.

Quando un URL viene fornito dall’utente o configurato nel pannello, deve essere validato. WordPress mette a disposizione funzioni sicure per richieste remote quando l’URL può essere controllato dall’utente. [225]

Un webhook in ingresso deve inoltre verificare che la richiesta provenga davvero dal sistema previsto. Senza questa verifica, un soggetto esterno potrebbe inviare dati falsi al sito.

Processi asincroni e WP-Cron

Le richieste API lente non dovrebbero bloccare il caricamento di una pagina o il completamento di un ordine.

Per esempio, quando un cliente conclude un acquisto WooCommerce, il sito dovrebbe salvare correttamente l’ordine prima di inviarlo a un gestionale esterno. L’invio può essere eseguito in background.

WordPress può utilizzare WP-Cron per pianificare attività automatiche. WP-Cron simula un sistema cron attraverso le richieste WordPress e può dipendere dalle visite al sito. [228]

Per siti con processi importanti o numerose sincronizzazioni può essere preferibile utilizzare un cron reale lato server, in modo da garantire una maggiore regolarità.

Le attività asincrone possono essere utilizzate per:

  • importare cataloghi;
  • aggiornare disponibilità;
  • inviare ordini;
  • scaricare immagini;
  • generare report;
  • inviare notifiche;
  • riprovare richieste fallite;
  • sincronizzare stati di spedizione.

WooCommerce utilizza Action Scheduler per molte attività asincrone. Le code devono essere controllate periodicamente per individuare azioni in attesa o fallite.

Test prima della pubblicazione

Un’integrazione API non dovrebbe essere attivata direttamente in produzione senza test.

È consigliabile utilizzare un ambiente di staging e, se disponibile, una sandbox dell’API esterna.

I test dovrebbero includere:

  • creazione di un record;
  • aggiornamento di un record;
  • gestione di dati mancanti;
  • gestione di valori non validi;
  • timeout e indisponibilità del servizio;
  • duplicazione della stessa richiesta;
  • token scaduto;
  • webhook con firma non valida;
  • sincronizzazione di molti record;
  • rollback o procedura di recupero;
  • verifica dei log;
  • test con utenti e ruoli diversi.

Nel caso di WooCommerce, è importante testare anche:

  • ordine con prodotto semplice;
  • ordine con prodotto variabile;
  • ordine con sconto;
  • ordine con spedizione;
  • ordine con più aliquote;
  • ordine annullato;
  • rimborso;
  • pagamento fallito;
  • ordine duplicato;
  • cliente ospite;
  • cliente registrato.

Quando sviluppare una soluzione custom

Una soluzione custom è utile quando un plugin pronto non gestisce correttamente il processo aziendale oppure richiede molte modifiche e componenti aggiuntivi.

Lo sviluppo personalizzato può essere la scelta migliore quando:

  • il gestionale utilizza un’API proprietaria;
  • sono presenti regole specifiche di sincronizzazione;
  • il catalogo ha una struttura complessa;
  • servono flussi bidirezionali;
  • è necessario gestire grandi quantità di dati;
  • occorrono log e controlli dettagliati;
  • l’azienda utilizza procedure particolari;
  • i plugin esistenti sono troppo generici;
  • l’integrazione deve rimanere attiva anche cambiando tema;
  • è necessario mantenere controllo completo sul codice.

Nel mio portfolio software sono presenti esempi di soluzioni sviluppate per esigenze specifiche, incluse integrazioni tra WordPress, WooCommerce e sistemi esterni.

Conclusione

Sviluppare un’integrazione tra WordPress e un’API esterna significa collegare il sito ai processi reali dell’azienda.

Una buona integrazione può ridurre attività manuali, evitare duplicazioni, aggiornare prodotti e ordini, mantenere sincronizzati più sistemi e rendere più affidabile la gestione quotidiana.

Il risultato dipende però dalla progettazione. Non basta inviare una richiesta HTTP: occorre definire flussi, responsabilità dei dati, autenticazione, sicurezza, gestione degli errori, log, code asincrone e manutenzione.

Un’integrazione efficace non è quella che si limita a scambiare dati, ma quella che continua a funzionare in modo controllabile anche quando un sistema esterno risponde lentamente, restituisce errori o modifica la propria API.

Quando un plugin pronto non è sufficiente, un plugin WordPress custom può trasformare una procedura manuale in un processo più stabile, automatizzato e adatto alle esigenze del progetto.

Posso aiutarti? Clicca qui!