Far leggere le tue fatture POP a un assistente AI (WordPress Abilities e WP-CLI)

Obiettivo

Permettere a un assistente AI collegato al tuo sito WordPress (o a uno script da riga di comando) di cercare le fatture e note di credito già generate da POP su WooCommerce, Paid Memberships Pro o Paid Member Subscriptions, e recuperarne XML, PDF o dati strutturati — senza dare accesso diretto al database o ai file.

Questo è un meccanismo diverso dal server MCP ospitato di POP (vedi mcp e mcp-remote): quello parla con l’API Cloud POP e crea nuovi documenti per qualsiasi piattaforma; questo lavora localmente sul tuo sito WordPress, sugli ordini che il tuo negozio ha già fatturato, e non genera nulla di nuovo — serve solo documenti già in cache.

Prerequisiti

• pop-wordpress 6.9.11 o superiore.
• Per il percorso WP-CLI: nessun’altra dipendenza, solo accesso SSH/shell al sito.
• Per il percorso assistente AI: il sito deve avere un’Abilities API registrata (funzione wp_register_ability() disponibile, tipicamente tramite il plugin “Abilities API”) e un server MCP che esponga le abilities del sito (tipicamente il plugin “MCP Adapter”) — pop-wordpress registra le proprie abilities solo se questi sono presenti, altrimenti non fa nulla.

Cosa espone

Quattro abilities, categoria pop:

• pop/search-invoices — cerca fatture/note di credito per provider, cliente, indirizzo, stato, tipo documento o intervallo di date; restituisce gli id documento da usare con le altre tre.
• pop/get-invoice-data — dati strutturati del documento (numero fattura, stato, totale, valuta, date, canale fiscale attivo, formati disponibili in cache).
• pop/get-invoice-xml — XML in cache (fattura/nota di credito).
• pop/get-invoice-pdf — metadati e URL del PDF in cache.

Passi

Percorso assistente AI (Abilities/MCP)

1. Installa e attiva i plugin Abilities API e MCP Adapter sul sito WordPress, oltre a pop-wordpress.
2. Collega il tuo assistente AI al server MCP del sito (indirizzo e autenticazione dipendono dal plugin MCP Adapter installato).
3. Chiedi all’assistente qualcosa come “Cerca le fatture del cliente Rossi di luglio”: l’assistente usa pop/search-invoices, poi pop/get-invoice-data/xml/pdf sul documento trovato.

Per default, ogni ability richiede la capability WordPress manage_options (filtrabile con wc_el_inv-abilities-capability), perché raggiungibile via HTTP.

Percorso WP-CLI

wp popapi invoice search --customer="Rossi" --date_from=2026-07-01
wp popapi invoice get <document_id> --provider=woocommerce
wp popapi invoice xml <document_id> --raw
wp popapi invoice pdf <document_id>

• search accetta --provider, --customer, --address, --status, --document_type, --date_from, --date_to, --limit (default 10, max 50), --offset.
• get/xml/pdf richiedono <document_id> come argomento posizionale, più --provider (obbligatorio se sul sito sono attivi più provider), --document_type, --parent_id (per le note di credito).
• Tutti e quattro accettano --format=table|csv|json|yaml|ids|count e --fields=<lista separata da virgola>.
• xml --raw stampa solo il contenuto XML, senza metadati.

I comandi WP-CLI non applicano il gate manage_options: l’accesso shell/WP-CLI al sito è già una barriera di fiducia più forte di una capability WordPress, quindi non serve --user.

Verifica

wp popapi invoice search --format=count deve restituire un numero coerente con gli ordini fatturati sul sito. Su un documento esistente, wp popapi invoice get <id> --provider=<provider> deve restituire i dati strutturati senza errori.

Errori comuni

• pop_ability_forbidden (403, solo percorso AI) — l’utente autenticato non ha la capability richiesta: verifica il ruolo o il filtro wc_el_inv-abilities-capability.
• pop_ability_invalid_provider — il sito ha più provider attivi (es. WooCommerce e PMPro insieme) e non hai specificato --provider/provider: il messaggio elenca i provider attivi tra cui scegliere.
• pop_ability_document_not_found — id documento inesistente per il provider/tipo indicato.
• pop_ability_xml_not_found / pop_ability_pdf_not_found — il documento non ha XML/PDF in cache: queste abilities servono solo documenti già generati, non ne creano di nuovi al volo.
• Nessuna ability registrata (silenzio, nessun errore) — mancano i plugin Abilities API/MCP Adapter: il percorso WP-CLI resta comunque disponibile indipendentemente da questi plugin.

Configurazione correlata

Per generare o inviare nuovi documenti da un assistente AI (non solo recuperare quelli esistenti), vedi mcp o mcp-remote, che lavorano a livello di API Cloud POP e non richiedono plugin aggiuntivi su WordPress.