WPForms REST API e Riferimenti API Abilities

WPForms 1.9.9 ha introdotto un'API REST di sola lettura basata sull'API Abilities di WordPress. Puoi elencare i moduli, recuperare la configurazione del modulo, recuperare e cercare le voci e ottenere statistiche sui moduli da qualsiasi client HTTP, dalla riga di comando, dal tuo codice PHP o da assistenti AI che parlano il Model Context Protocol (MCP).

Se hai cercato "WPForms REST API" e sei arrivato qui, è questa. Non esiste un'API REST separata; l'integrazione con l'API Abilities è il modo in cui WPForms espone i suoi dati tramite HTTP.

Cos'è l'API Abilities

L'API Abilities è una funzionalità principale di WordPress aggiunta in WordPress 6.9. Consente ai plugin di dichiarare capacità individuali (chiamate abilities) con un nome, uno schema di input, uno schema di output e una funzione di callback per i permessi. WordPress espone quindi ogni ability registrata automaticamente tramite l'API REST all'indirizzo /wp-json/wp-abilities/v1/abilities/<ability>/run e ai client AI compatibili con MCP tramite il plugin ufficiale dell'adattatore MCP.

WPForms registra un set di abilities di sola lettura sotto lo spazio dei nomi wpforms/. Ogni ability esegue gli stessi controlli di capacità di WPForms utilizzati nell'area di amministrazione (wpforms_current_user_can()), quindi le superfici REST e MCP ereditano il modello di permessi esistente anziché introdurne uno nuovo.

Chiamare un'Ability

Ogni ability può essere invocata tramite due trasporti. Il risultato è identico; scegli quello che si adatta all'ambiente di chiamata.

API REST

Invia una richiesta GET autenticata a /wp-json/wp-abilities/v1/abilities/<ability>/run. Poiché ogni ability di WPForms è di sola lettura, viene accettato solo GET; POST restituisce 405 Method Not Allowed.

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/list-forms/run?input%5Blimit%5D=10&input%5Bstatus%5D=publish"

PHP

Da qualsiasi plugin, tema o codice personalizzato che viene eseguito dopo che l'azione wp_abilities_api_init è stata attivata, recupera l'ability con wp_get_ability() e chiama il suo metodo execute(). Passa l'input come array associativo di parametri (gli stessi nomi elencati nella tabella dei parametri di ogni ability).

$ability = wp_get_ability( 'wpforms/list-forms' );

if ( $ability ) {
    $result = $ability->execute(
        [
            'limit'  => 10,
            'status' => 'publish',
        ]
    );

    if ( is_wp_error( $result ) ) {
        // Handle error.
        return;
    }

    // $result['forms']  array of form summaries
    // $result['total']  total count (integer)
}

Autenticazione

Il trasporto REST utilizza l'autenticazione standard di WordPress. Il metodo consigliato per i client esterni sono le Password per applicazioni, che sono integrate nel core di WordPress e non richiedono plugin aggiuntivi.

Generazione di una Password per applicazioni

1. Accedi come utente WordPress i cui permessi devono essere utilizzati per le chiamate.
2. Vai su Utenti » Profilo e scorri fino alla sezione Password per applicazioni.
3. Inserisci un nome per l'integrazione e fai clic su Aggiungi nuova password per l'applicazione.
4. Copia la password generata. WordPress la mostra solo una volta.

Per un riferimento più approfondito, inclusi gli endpoint REST per la gestione programmatica delle password per le applicazioni, consulta la Guida all'integrazione delle password per le applicazioni del team principale di WordPress.

Invio delle credenziali

Passa il nome utente e la password dell'applicazione come autenticazione HTTP Basic ad ogni richiesta.

Con curl

Imposta l'URL del tuo sito come variabile d'ambiente in modo che gli esempi in questo documento siano eseguibili così come sono:

export WP_SITE="https://your-wordpress-site.com"

Quindi aggiungi il flag -u a ogni comando curl. Il valore del flag è il tuo nome utente, seguito da due punti, seguito dalla tua password dell'applicazione (senza spazi).

Con Postman, Insomnia o altri client

Imposta il tipo Auth della richiesta su Basic Auth e fornisci il tuo nome utente e la password dell'applicazione. Il client gestisce la codifica per te.

Impostazione manuale dell'intestazione

Invia le tue credenziali come intestazione Authorization codificata in base64:

Combina il tuo nome utente e la password dell'applicazione in un'unica stringa, separati da due punti (senza spazi), e codifica il risultato in base64 utilizzando uno strumento a tua scelta (comando base64, codificatore online o libreria standard del tuo linguaggio). Invia il valore codificato ad ogni richiesta come intestazione Authorization, nel formato Authorization: Basic <encoded>.

Gli esempi di richiesta nel resto di questo documento omettono il flag di autenticazione per leggibilità. Aggiungi il flag -u (o l'intestazione Authorization) ad ogni richiesta reale, altrimenti l'API restituirà 401 Unauthorized.

Permessi

Ogni abilità controlla una specifica capacità di WPForms prima dell'esecuzione. I controlli falliti restituiscono un WP_Error con stato HTTP 403.

Riferimento abilità

Tutte le abilità sono di sola lettura e idempotenti. Gli errori vengono restituiti come oggetti WP_Error serializzati in JSON con i campi code, message e data.status.

wpforms/list-forms

Elenca i moduli con metadati di riepilogo. Disponibile in Lite e Pro.

Parametri

Richiesta di esempio

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/list-forms/run?input%5Blimit%5D=10&input%5Bstatus%5D=publish"

Risposta di esempio

{
  "forms": [
    {
      "id": 123,
      "title": "Contact Form",
      "status": "publish",
      "created": "2026-01-27 10:00:00",
      "modified": "2026-02-15 14:30:00",
      "author": 1
    }
  ],
  "total": 5
}

wpforms/get-form

Recupera un singolo modulo, inclusa una selezione curata delle sue impostazioni e, facoltativamente, la sua configurazione dei campi. Disponibile in Lite e Pro.

Parametri

Richiesta di esempio

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/get-form/run?input%5Bform_id%5D=123&input%5Binclude_fields%5D=true"

Risposta di esempio

{
  "id": 123,
  "title": "Contact Form",
  "status": "publish",
  "created": "2026-01-27 10:00:00",
  "modified": "2026-02-15 14:30:00",
  "author": 1,
  "settings": {
    "form_title": "Contact Form",
    "form_desc": "Get in touch with us",
    "submit_text": "Submit",
    "ajax_submit": true,
    "honeypot": true,
    "antispam": true
  },
  "fields": [
    {
      "id": 1,
      "type": "text",
      "label": "Name",
      "description": "",
      "required": true,
      "size": "medium"
    }
  ]
}

L'oggetto settings restituito da questa abilità è un sottoinsieme curato e non sensibile (titolo, descrizione, testo di invio, flag di invio AJAX, honeypot, anti-spam). Le impostazioni di notifica, conferma e integrazione non sono esposte.

wpforms/get-form-stats

Restituisce le statistiche di invio per un modulo. La forma della risposta differisce tra Lite e Pro.

Parametri

Richiesta di esempio

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/get-form-stats/run?input%5Bform_id%5D=123"

Risposta Lite

{
  "form_id": 123,
  "entries_available": false,
  "message": "Entry statistics require WPForms Pro. Upgrade to access detailed form submission data."
}

Risposta Pro

{
  "form_id": 123,
  "total_entries": 156,
  "unread_entries": 12,
  "starred_entries": 8,
  "entries_available": true
}

wpforms/get-entry-summaries

Elenco paginato di riepiloghi delle voci per un singolo modulo. Solo Pro.

Parametri

Richiesta di esempio

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/get-entry-summaries/run?input%5Bform_id%5D=123&input%5Btype%5D=unread&input%5Blimit%5D=20"

Risposta di esempio

{
  "entries": [
    {
      "id": 456,
      "form_id": 123,
      "date": "2026-02-15 14:32:10",
      "status": "",
      "viewed": false,
      "starred": true
    }
  ],
  "total": 15,
  "form_id": 123
}

wpforms/get-entry

Recupera una singola voce tramite ID, inclusi tutti i valori dei campi. Solo Pro.

Parametri

Richiesta di esempio

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/get-entry/run?input%5Bentry_id%5D=456"

Risposta di esempio

{
  "id": 456,
  "form_id": 123,
  "date": "2026-02-15 14:32:10",
  "modified": "2026-02-15 15:00:00",
  "status": "",
  "viewed": true,
  "starred": false,
  "ip_address": "192.168.1.100",
  "fields": [
    {
      "id": 1,
      "name": "Name",
      "value": "John Doe",
      "type": "text"
    }
  ]
}

L'indirizzo IP nella risposta può essere mascherato. Aggiungi add_filter( 'wpforms_abilities_mask_ip_address', '__return_true' ) al codice del tuo sito; quando abilitato, gli indirizzi IPv4 appaiono con i loro ultimi tre ottetti sostituiti da asterischi (ad esempio, ***.***.***.100).

wpforms/search-entries

Cerca voci in un singolo modulo o in tutti i moduli con filtri full-text, specifici per campo, stato e intervallo di date. Solo Pro.

Parametri

Richiesta di esempio

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/search-entries/run?input%5Bform_id%5D=5&input%5Bsearch%5D=john%40example.com&input%5Bpage%5D=1&input%5Blimit%5D=20"

Risposta di esempio

{
  "entries": [
    {
      "id": 142,
      "form_id": 5,
      "date": "2026-02-15 14:32:10",
      "status": "",
      "viewed": false,
      "starred": true,
      "fields": [
        { "id": 1, "name": "Name",  "value": "John Doe",         "type": "text"  },
        { "id": 2, "name": "Email", "value": "[email protected]", "type": "email" }
      ]
    }
  ],
  "total": 47,
  "total_pages": 5,
  "page": 1,
  "limit": 20
}

Utilizzo di WPForms con Client MCP

Ogni funzionalità di WPForms è registrata con mcp.public impostato su true, il che significa che i client AI compatibili con MCP (Claude Desktop, Cursor e altri) le scoprono automaticamente una volta che il sito WordPress è connesso tramite il plugin wordpress/mcp-adapter. Dopo l'installazione, non è richiesta alcuna ulteriore configurazione lato WPForms; le funzionalità appaiono nell'elenco degli strumenti del client sotto la categoria WPForms e rispettano le stesse callback di autorizzazione utilizzate dall'API REST.

Scoperta delle Funzionalità in Programma

Per enumerare le funzionalità disponibili su un sito invece di codificarle in modo fisso i loro ID:

# List all registered abilities on the site
curl "$WP_SITE/wp-json/wp-abilities/v1/abilities"

# Fetch the schema for a single ability
curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/list-forms"

La risposta include l'ID, l'etichetta, la descrizione, la categoria e gli schemi di input e output completi di ciascuna funzionalità, che sono sufficienti per creare un client generico senza conoscere in anticipo la superficie specifica di WPForms.

Link Correlati

• Introduzione all'API delle Funzionalità di WordPress (developer.wordpress.org)
• wordpress/mcp-adapter su GitHub
• Protocollo di Contesto del Modello