Al giorno d’oggi avere un sito e-commerce bello e professionale è davvero qualcosa alla portata di tutti, anche di chi non sa nulla di programmazione.

Ti basta fare una breve ricerca on-line per trovare decine di piattaforme (Shopify, BigCommerce e Magento per citarne alcune) che ti permettono di creare in pochissimo tempo un negozio on-line.

Le possibilità, però, non finiscono qui.

Una scelta sempre molto apprezzata, soprattutto da chi possiede già un sito web realizzato in WordPress, consiste in WooCommerce.

Semplice e molto intuitivo, per certi versi è simile a Shopify e BigCommerce, ma con un’unica grande differenza: è un plugin di WordPress e quindi è completamente legato a questa piattaforma.

Grazie ad esso puoi gestire tutti gli aspetti del tuo negozio: puoi creare prodotti, definire prezzi e sconti, caricare le tariffe di spedizione e le aree geografiche di vendita, gestire gli ordini e lo stock di magazzino.

Questa soluzione si presta bene quando hai volumi piccoli e non hai applicazioni gestionali dedicate.

Nelle realtà più grandi, invece, la situazione potrebbe essere differente: magari c’è un ERP a supporto dei processi aziendali e pensare di gestire un e-commerce come se fosse un sistema stand-alone non è certo la scelta migliore.

Fortunatamente WooCommerce mette a disposizione un nutrito set di API Rest che possono essere usate per collegarlo ai sistemi gestionali.

In questo articolo desidero introdurti all’utilizzo queste API, in particolare di quelle che servono per gestire i Prodotti, i Clienti e gli Ordini di Vendita.

Alla fine di questo tutorial sarai in grado di creare una soluzione integrata che sfrutta da un lato la coppia WooCommerce + WordPress (a mio avviso uno dei migliori Content Management System in circolazione) e dall’altro Oracle APEX, sicuramente molto più adatto per implementare applicazioni di natura gestionale.

Buona lettura!

Prima di Iniziare

WooCommerce è una soluzione che molte aziende, soprattutto quelle con volumi d’affari non troppo elevati, adottano per iniziare a lanciarsi nel mondo dell’e-commerce.

Questo tutorial è rivolto sicuramente a chi desidera integrare WooCommerce con una applicazione Oracle APEX ma non solo.

Può essere d’aiuto a tutti coloro che vogliono prendere dimestichezza che le funzionalità messe a disposizione da Oracle APEX per integrare le proprie applicazioni gestionali con piattaforme esterne di e-commerce o altro.

Se non hai già un sito WordPress puoi crearne uno gratuitamente registrandoti su https://wordpress.com/.

Ovviamente il sito andrà un minimo configurato: ad esempio dovrai scegliere un tema e installare installare il plugin di WooCommerce.

Non preoccuparti, non è nulla di complicato e se non sai da dove iniziare puoi trovare decide di risorse e guide on-line che ti spiegano come fare.

A questo link, invece, puoi trovare l’elenco di tutte le API di WooCommerce.

Step 1: Crea una applicazione Oracle APEX

La prima cosa che faremo sarà creare l’applicazione APEX che utilizzeremo per testare i connettori WooCommerce.

• Accedi ad Oracle APEX e vai nell’APP Builder
• Clicca su Create APP > New Application per creare una nuova applicazione

• Per il momento limitiamoci alle configurazioni di base:
  • Dai un nome alla tua applicazione (io l’ho chiamata WooCommerce APP)
  • Seleziona un tema ed un logo

Nei prossimi paragrafi andremo a costruire passo passo tutte le funzionalità necessarie per collegarla al tuo sito.

Step 2: Attiva le API di WooCommerce

Per integrare Oracle APEX con WooCommerce è necessario attivare le API di integrazione.

Come immaginerai, il prerequisito è che WooCommerce sia stato già installato nel sito WordPress.

• Accedi al sito WordPress
• Clicca su WooCommerce > Impostazioni

• Clicca su Avanzate > API REST

• Clicca su Aggiungi Chiave per generare una API Key da utilizzare in Oracle APEX

• Inserisci le informazioni richieste:
  • Descrizione: specifica il nome che preferisci
  • Utente: specifica l’utente WordPress proprietario della chiave
  • Autorizzazioni: specifica il tipo di grants che vuoi concedere con la chiave, ad esempio Leggi/Scrivi

• Quando hai fatto premi Genera Chiave API

• WooCommerce genererà una API Key User e una API Key Password. Ti consiglio di copiarle e conservarle perché poi non sarà più possibile visualizzarle e dovrai eventualmente generarne di nuove.

Step 3: Collega l’applicazione APEX a WooCommerce

Grazie alle API Keys appena sfornate, possiamo finalmente collegare la nostra applicazione APEX.

WooCommerce mette a disposizione numerose API REST (per maggiori dettagli puoi consultare la documentazione a questo link) che possono essere utilizzate per gli scopi più disparati.

Ad esempio, puoi esportare e modificare via API i prodotti, ma anche i clienti e gli ordini.

A questo punto è lecito chiedersi: in che modo APEX può connettersi a WooCommerce?

Devi sapere che Oracle mette a disposizione diversi metodi per collegarsi a servizi REST esposti da applicazioni esterne.

Due sono quelli principali: Rest Data Sources e il package PL-SQL apex_web_service (queste ultimo utile soprattutto quando devi implementare integrazioni più avanzate).

Se non sai di cosa sto parlando, di consiglio di dare una occhiata a questo articolo dove spiego come chiamare un servizio REST in Oracle APEX.

Nei prossimi paragrafi ti mostrerò nel dettaglio come utilizzare alcune API di WooCommerce in Oracle APEX, partendo da quelle che permettono di gestire i prodotti che vogliamo vendere attraverso il nostro on-line store.

Step 4: Gestione dei Prodotti

Prima di buttarci a capofitto nella creazione dei connettori, creiamo direttamente dentro WooCommerce qualche prodotto di test che ci servirà per iniziare a sviluppare le varie integrazioni.

Nella realtà questi articoli potrebbero essere stati creati a loro volta attraverso una API Rest: vedremo come fare più avanti.

Per creare un Prodotto

• Vai in Prodotti > Aggiungi Nuovo

• Inserisci le informazioni richieste, ad esempio:
  • Nome del Prodotto
  • Descrizione del Prodotto
  • Codice Prodotto
  • Prezzo
  • ecc…

Quali e quante informazioni inserire dipendono dal tipo di prodotto che stai configurando e dalle caratteristiche dei servizi che vuoi offrire attraverso il tuo negozio on-line.

WooCommerce da questo punto di vista offre molte possibilità: puoi definire prodotto fisici ma anche prodotti virtuali.

Puoi caricare un prezzo di listino ed un prezzo di offerta, definire di regole di up-selling e cross-selling e molto altro.

Non è mia intenzione spiegare in questo articolo come funziona WooCommerce: per questo ti consiglio di leggere qui.

Come visualizzare i Prodotti

Partiamo con esempio molto semplice: creiamo una pagina APEX dalla quale possiamo visualizzare i Prodotti che sono disponibili nell’e-commerce.

• Accedi all’APP Builder
• Vai in Shared Components > Data Sources > Rest Data Source

• Clicca Create

• Seleziona l’opzione From Scratch e premi Next

• Specifica le proprietà generali
  • REST Data Source Type: Simple HTTP
  • Name: WooCommerce Products
  • URL Endpoint: inserisci l’URL del servizio REST che, se guardiamo la documentazione delle API WooCommerce, è questo: https://yourdomain/wp-json/wc/v3/orders (sostituisci yourdomain con l’hostname del tuo sito WordPress)

• Premi Next

• Nella seguente sezione lascia pure i valori di default e premi Next

• Premi nuovamente Next

• Nella sezione Authentication specifica le seguenti opzioni
  • Authentication Required: Yes
  • Authentication Type: Basic Authentication
  • Username: inserisci l’API Key User generata precedentemente
  • Password: API Key Password generata precedentemente

• Premi Discover

• Se la connessione va a buon fine dovresti vedere una Preview dei record, letti direttamente dal database di WooCommerce.
• Premi Create REST Data Source per completare la creazione dell’Origine Dati.

L’Origine Dati di tipo REST è stata creata e può essere già utilizzata per alimentare un Report APEX: a tal proposito ho intenzione di creare un Interactive Report + Form.

• Apri l’APP Builder e premi Create Page
• Seleziona il tipo pagina Form e successivamente Report with Form

• Seleziona le seguenti opzioni
  • Report Type: Interactive Report
  • Report Page Name: Products
  • Form Page Name: Product Details
  • Form Page Name: Modal Dialog

• Seleziona l’Origine Dati REST che abbiamo precedentemente configurato

• Seleziona la Primary Key ID e premi Create

Oracle APEX creerà due pagine: Products e Product Details

• Clicca su Products

La prima cosa che notiamo di diverso rispetto alla struttura di un Interactive Report + Form basato su tabella è che manca il bottone per creare un nuovo Prodotto.

Questo dipende dal fatto che l’Origine Dati REST che abbiamo configurato ha solo un tipo di operazione GET.

Questo non deve spaventarci: tra non molto ti mostrerò come implementare l’aggiornamento dei dati attraverso le API Rest.

Per completare la configurazione dell’Interactive Report ho successivamente applicato le seguenti modifiche

• Ho nascosto tutte le colonne eccetto quelle evidenziate

• Per le colonne PRICE_HTML, SHORT_DESCRIPTION, DESCRIPTION ho disattivato l’opzione Escape Special Characters

• Ho configurato la colonna PERMALINK in questo modo:
  • Type: Link
  • Target Type: URL
  • URL: #PERMALINK#

Questo è il risultato finale:

Cliccando sul link Edit viene aperta una form APEX che mostra i dettagli dell’articolo come il suo codice, il nome, una descrizione e il prezzo.

Nel prossimo paragrafo vedremo come gestire l’aggiornamento delle proprietà di un prodotto attraverso le API Rest.

Come modificare un Prodotto

Ora che abbiamo capito come fare una richiesta GET usando le API di WooCommerce, possiamo sperimentare altri tipi di operazioni.

Ad esempio, potremmo provare ad aggiornare il prezzo di un Prodotto.

Quando si tratta di richiamare un’API Rest in Oracle APEX, che si tratti di eseguire delle operazioni di tipo PUT (ovvero di aggiornamento) piuttosto che di tipo POST (creazione), si possono usare due metodi.

Il primo, forse più immediato per chi sa sviluppare codice, è grazie al package PL-SQL apex_web_service grazie al quale possiamo chiamare una API REST usando una procedura PL-SQL.

Tuttavia, devi sapere che possiamo ottenere lo stesso risultato con un approccio totalmente Low-Code, utilizzando ovviamente le potenzialità degli oggetti Rest Data Source.

In questo tutorial utilizzerò questo secondo metodo.

Per aggiornare il Prezzo di un Prodotto WooCommerce devi richiamare l’API già vista concatenando all’URL l’ID del Prodotto che deve essere modificato https://yourdomain/wp-json/wc/v3/products/{insert product ID}

Questo è un esempio di Richiesta JSON che dovremo utilizzare

{
"regular_price": "81"
}

Iniziamo con la configurazione della Rest Data Source

• Vai in Shared Components > REST Data Sources e seleziona l’Origine Dati REST WooCommerce Products

• Vai alla sezione Operations
• Dovresti vedere disponibile una Operazione di tipo GET: è stata creata automaticamente da APEX quando abbiamo configurato la Rest Data Source.
• Clicca Add Operation

• Definisci una nuova Operation fatta in questo modo:
  • URL Pattern: inserisci la stringa :product (attenzione ad inserire il carattere ‘:’). Come vedremo tra poco, useremo questo parametro per passare alla chiamata PUT l’ID del Prodotto.
  • HTTP Method: PUT
  • Database Operation: Update Row
  • Request Body: inserisci il seguente template

{
"regular_price":"#REGULAR_PRICE#"
}

• Vai in Operation Parameters ed definisci i seguenti parametri
  • product: di tipo URL Pattern Variabile verrà usato per passare alla chiamata REST l’ID del Prodotto da aggiornare
  • response: di tipo Request / Response Body sarà usato per visualizzare la Response JSON

Ora possiamo richiamare l’operazione REST che abbiamo creato dalla form APEX vista nel paragrafo precedente.

• Accedi all’APP Builder e seleziona la Form APEX Product Details

• Seleziona la Form Page Product Details

• Crea un Page Items di tipo Display Only che utilizzeremo per visualizzare la Response JSON

• Espandi il nodo Parameters della Page Region Product Details.

• Poiché l’Origine Dati di questa form è di tipo REST, Oracle APEX mostrerà tutti parametri delle Operazioni che sono state configurate all’interno della Rest Data Source.

• Seleziona il parametro product e configuralo in questo modo
  • Value Type: Item
  • Value Item: PX_ID

• Allo stesso modo, seleziona il parametro response
  • Value Type: Item
  • Value Item: PX_RESPONSE

• Crea un Page Button di nome Save

• Clicca su Processi e crea un nuovo Page Process di nome UpdateProduct

• Configura il Processo come di tipo Form – Automatic Row Processing (DML)

• Esegui la Preview della Pagina.

Se tutto funziona come previsto, quando salverai i dati Oracle APEX eseguirà l’operazione di tipo PUT ed aggiornerà il prezzo del Prodotto in WooCommerce

• Nel campo PX_RESPONSE verrà visualizzata la Response JSON

Step 5: Gestione dei Clienti

Arrivati a questo punto credo tu abbia capito in che modo possiamo collegare Oracle APEX con WooCommerce.

Proviamo a creare dei connettori per gestire i Clienti.

Come visualizzare i Clienti

Per recuperare la lista dei Clienti registrati nel sito dobbiamo utilizzare la seguente API Rest:

https://yourdomain/wp-json/wc/v3/customers

Mentre per recuperare i dettagli di uno specifico cliente useremo questa:

https://yourdomain/wp-json/wc/v3/customers/{insert customer ID}

Come fatto per i Prodotti, partiamo dalla creazione guidata di una Rest Data Source

• Accedi all’APP Builder
• Vai in Shared Components > Data Sources > Rest Data Source
• Clicca Create e seleziona l’opzione From Scratch.
• Premi Next.

• Specifica le proprietà dell’Origine Dati
  • REST Data Source Type: Simple HTTP
  • Name: WooCommerce Customers
  • URL Endpoint: inserisci l’URL del servizio REST: https://yourdomain/wp-json/wc/v3/customers (sostituisci yourdomain con l’hostname del sito WordPress)

• Lascia le opzioni di default e quando arrivi allo step Authentication inserisci le credenziali per l’utilizzo delle API (puoi usare sempre le stesse).

• Premi Discover per verificare che la connessione avvenga correttamente e successivamente premi Create Rest Data Source per completare la procedura guidata.

Una volta creata l’Origine Dati esterna, puoi creare un Report APEX per visualizzare i Clienti direttamente all’interno dell’applicazione WooCommerce APP.

Ovviamente dovrai usare lo stesso metodo che ti ho spiegato per configurare la pagina Prodotti.

In questo caso, però, ti chiederei di aspettare un secondo.

Infatti, prima di creare il Report APEX, vorrei che definissimo l’operazione PUT, necessaria per permette la modifica del record Cliente attraverso le API Rest.

Come modificare un Cliente

Per modificare le informazioni di un Cliente va creata una operazione di tipo PUT. Questa è l’API che dovrai utilizzare:

https://yourdomain/wp-json/wc/v3/customers/{insert customer ID}

Questo è un esempio di Request JSON per modificare i campi first_name e last_name di un oggetto Cliente:

{
  "first_name": "John",
  "last_name": "Doe"
}

• Aggiungi alla Rest Data Source WooCommerce Customer una nuova Operation di tipo PUT
  • URL Pattern: inserisci la stringa :customer
  • HTTP Method: PUT
  • Database Operation: Update Row
  • Request Body Template:

{
  "last_name":#LAST_NAME3#, 
  "first_name":#FIRST_NAME3#
}

Come avrai notato, nel Request Body Template non andiamo ad inserire dei valori fissi, piuttosto usiamo dei placeholders ( #LAST_NAME3# e #FIRST_NAME3# ).

Cosa sono esattamente e come faccio a sapere quali sono i placeholders corretti da utilizzare?

Su questo aspetto vale la pena spendere qualche minuto.

Devi sapere che le API Rest permettono ai sistemi collegati di scambiarsi dei messaggi in formato JSON.

Ad esempio, questo qui sotto è un esempio di messaggio che WooCommerce restituisce quando un sistema come Oracle APEX chiede i dettagli di un cliente usando la chiamata GET https://yourdomain/wp-json/wc/v3/customers/{insert customer ID}.

In particolare ti faccio notare che ci sono 3 coppie di campi first_name e last_name che rappresentano rispettivamente nome e cognome del cliente, nome e cognome del cliente di fatturazione, nome e cognome del cliente di spedizione.

Quando crei una Rest Data Source tramite la procedura guidata, Oracle APEX legge il messaggio JSON ed estrae da quest’ultimo i campi, che successivamente vengono univocamente identificati da placeholders.

Per sapere quali sono i placeholders corretti da usare devi vedere le proprietà dell’Origine Dati:

• Vai in Shared Components > Rest Data Source e seleziona l’Origine Dati WooCommerce Customers
• Vai alla sezione Data Profile e clicca su Edit Data Profile

• Cerca il record con selector=first_name per scoprire come è stato mappato il relativo campo JSON. Nel mio caso il campo che voglio aggiornare è quello evidenziato, che corrisponde al placeholders FIRST_NAME3

Usando la stessa API puoi modificare l’Indirizzo di Spedizione. Ecco un esempio di JSON Request:

{
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "Storm Creek",
    "address_1": "110 Demo Drive",
    "address_2": "Suite 110",
    "city": "Minneapolis",
    "state": "MN",
    "postcode": "94203",
    "country": "US"
  }
}

Ora che ti ho spiegato come creare il template della JSON Request, possiamo andare avanti.

Come fatto per i Prodotti, creiamo un Interactive Report + Form usando l’Origine Dati WooCommerce Customers

• Apri l’APP Builder e premi Create Page
• Seleziona il tipo pagina Form e successivamente Report with Form

• Seleziona le seguenti opzioni
  • Report Type: Interactive Report
  • Report Page Name: Customers
  • Form Page Name: Customer Details
  • Form Page Name: Modal Dialog

• Seleziona l’Origine Dati REST WooCommerce Customers

• Seleziona la Primary Key (colonna ID) e premi Create

• Oracle APEX dovrebbe creare anche in questa caso due pagine, Customers e Customer Details, che puoi personalizzare come ritieni più opportuno

• Seleziona la Form Page Customer Details

• In questo caso, poiché l’Origine Dati scelta aveva già definito un’operazione di tipo PUT, Oracle APEX ha creato automaticamente il bottone Save e il Page Process di tipo Form – Automatic Row Processing (DML)

Quello che rimane da fare è mappare i Page Items della Form con i parametri dell’Operazione REST da chiamare.

• Espandi il nodo Items: notiamo subito che ci sono in totale 3 coppie di campi FIRST_NAME e LAST_NAME previsti nell’API Rest esposta da WooCommerce.

Adesso sappiamo che questi campi sono stati creati automaticamente da Oracle APEX e sono diretta conseguenza della Response JSON restituita da WooCommerce.

Quelli che ci interessano sono i seguenti: PX_FIRST_NAME3 e PX_LAST_NAME3 che lasceremo visibili mentre possiamo nascondere tutti gli altri.

Ora possiamo finalmente eseguire la Preview e verificare che il connettore funzioni a dovere.

Step 6: Gestione degli Ordini

Completiamo questo tutorial introducendo le API Rest che ti permettono di gestire gli Ordini di Vendita.

Come visualizzare gli Ordini

Come visto per Prodotti e Clienti, anche in questo caso dovrai creare una Rest Data Source usando la seguente API Rest di WooCommerce

https://yourdomain/wp-json/wc/v3/orders/

Questa è la definizione dell’Origine Dati

Come modificare un Ordine

Anche per gli Ordini puoi effettuare delle operazioni di modifica. Tieni però a mente che non tutti i campi di un ordine di vendita sono modificabili (devi fare riferimento alle API di WooCommerce).

Ad esempio, possiamo modificare lo stato di un ordine di vendita facendo una chiamata di tipo PUT

https://yourdomain/wp-json/wc/v3/orders/{insert order ID}

Questo è un esempio di JSON Request che devi usare

{
  "status": "completed"
}

Questo è un esempio di Operazione PUT che puoi usare per aggiornare lo stato dell’ordine

Lascio a te la creazione di un Report APEX che visualizzi gli Ordini di Vendita e che permetta di aggiornarne lo stato.

Conclusioni

Siamo arrivati alla fine di questo tutorial su come collegare WooCommerce di WordPress con Oracle APEX.

Ovviamente questa guida non è certo sufficiente per capire ogni singolo aspetto di come utilizzare le API REST di WooCommerce.

Ciò nonostante, se leggi gli approfondimenti e se capisci i meccanismi che ci sono dietro alle integrazioni REST, sono certo che riuscirai a realizzare il tuo progetto.

Un’altra cosa importante che ci tengo a sottolineare è che non hai scritto una riga di codice, te ne sei accorto?

Tutto ciò grazie all’enorme versatilità di Oracle APEX che, seppur non offrendo dei connettori nativi come altre piattaforme low-code, è comunque in grado di integrarsi senza problemi con qualsiasi tipo di Origine Dati esterna.

Bene, direi che è tutto per il momento. Non mi resta che augurarti un buon lavoro!

Fammi sapere nei commenti se hai trovato questo articolo interessante e condividilo pure con i tuoi amici e colleghi, mi farebbe molto piacere!

Un abbraccio

Daniele