Riferimento alle API REST e Abilities di WPForms

La versione 1.9.9 di WPForms ha introdotto un'API REST in sola lettura basata sull'API Abilities di WordPress. È possibile visualizzare l'elenco dei moduli, recuperare le impostazioni dei moduli, recuperare e cercare i dati inseriti, nonché estrarre le statistiche dei moduli da qualsiasi client HTTP, dalla riga di comando, dal proprio codice PHP o da assistenti AI che utilizzano il Model Context Protocol (MCP).

Se hai cercato "WPForms REST API" e sei arrivato qui, sei nel posto giusto. Non esiste un'API REST separata; l'integrazione con l'API di Abilities è il modo in cui WPForms rende accessibili i propri dati tramite HTTP.

Cos'è l'API Abilities

L'API delle funzionalità è una funzionalità integrata in WordPress introdotta nella versione 6.9. Consente ai plugin di dichiarare singole funzionalità (chiamate capacità) con un nome, uno schema di input, uno schema di output e una callback per le autorizzazioni. WordPress rende quindi automaticamente disponibili tutte le funzionalità registrate 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 una serie di autorizzazioni di sola lettura sotto il wpforms/ spazio dei nomi. Ogni funzione esegue gli stessi controlli di autorizzazione di WPForms utilizzati nell'area di amministrazione (wpforms_current_user_can()), pertanto le interfacce REST e MCP ereditano il modello di autorizzazioni esistente anziché introdurne uno nuovo.

Attivare un'abilità

Ogni abilità può essere attivata tramite due metodi. Il risultato è lo stesso; scegli quello più adatto al contesto in cui la chiami.

API REST

Invia un messaggio autenticato GET richiesta di /wp-json/wp-abilities/v1/abilities/<ability>/run. Poiché tutte le impostazioni di WPForms sono di sola lettura, solo GET è accettato; 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 venga eseguito dopo il wp_abilities_api_init l'azione è stata attivata, recupera l'abilità con wp_get_ability() e chiamarlo execute() metodo. Passare l'input come array associativo di parametri (gli stessi nomi elencati nella tabella dei parametri di ciascuna abilità).

$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 protocollo REST utilizza l'autenticazione standard di WordPress. Il metodo consigliato per i client esterni è quello delle password di applicazione, che sono integrate nel core di WordPress e non richiedono alcun plugin aggiuntivo.

Creazione di una password per l'applicazione

1. Accedi con l'account utente di WordPress con cui devono essere eseguite le chiamate.
2. Vai su Utenti » Profilo e scorri fino alla sezione " Password delle applicazioni ".
3. Inserisci un nome per l'integrazione e clicca su " Aggiungi nuova password dell'applicazione".
4. Copia la password generata. WordPress la mostra solo una volta.

Per ulteriori informazioni, compresi gli endpoint REST per la gestione delle password delle applicazioni a livello di programmazione, consulta la Guida all'integrazione delle password delle applicazioni redatta dal team di sviluppo di WordPress.

Invio delle credenziali

Inserisci il nome utente e la password dell'applicazione tramite autenticazione HTTP Basic in ogni richiesta.

Con curl

Imposta l'URL del tuo sito come variabile d'ambiente in modo che gli esempi contenuti in questa documentazione possano essere eseguiti così come sono:

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

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

Con Postman, Insomnia o altri client

Imposta il tipo di autenticazione della richiesta su " Basic Auth " e inserisci il tuo nome utente e la password dell'applicazione. Il client si occuperà automaticamente della codifica.

Impostazione manuale dell'intestazione

Invia le tue credenziali codificate in base64 Authorization intestazione:

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

Negli esempi di richiesta riportati nel resto di questo documento, il flag di autenticazione è stato omesso per facilitare la lettura. Aggiungere il -u bandiera (o il Authorization intestazione) a ogni richiesta effettiva, altrimenti l'API restituisce 401 Unauthorized.

Autorizzazioni

Ogni funzione verifica una specifica funzionalità di WPForms prima di essere eseguita. Se la verifica non va a buon fine, restituisce un WP_Error con lo stato HTTP 403.

Riferimenti sulle abilità

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

wpforms/elenco-moduli

Elenco dei moduli con metadati di riepilogo. Disponibile nelle versioni Lite e Pro.

Parametri

Esempio di richiesta

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

Esempio di risposta

{
  "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, compreso un sottoinsieme selezionato delle sue impostazioni e, facoltativamente, la configurazione dei campi. Disponibile nelle versioni Lite e Pro.

Parametri

Esempio di richiesta

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

Esempio di risposta

{
  "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"
    }
  ]
}

Il settings L'oggetto restituito da questa funzionalità è un sottoinsieme selezionato e non sensibile (titolo, descrizione, testo di invio, flag di invio AJAX, honeypot, anti-spam). Le impostazioni relative alle notifiche, alle conferme e all'integrazione non sono visibili.

wpforms/statistiche-modulo

Statistiche relative all'invio dei moduli. La struttura della risposta varia a seconda della versione Lite o Pro.

Parametri

Esempio di richiesta

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

Risposta semplificata

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

Risposta professionale

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

wpforms/ottenere-i-riassunti-delle-voci

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

Parametri

Esempio di richiesta

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"

Esempio di risposta

{
  "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 in base all'ID, inclusi tutti i valori dei campi. Solo versione Pro.

Parametri

Esempio di richiesta

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

Esempio di risposta

{
  "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 nascosto. Aggiungi add_filter( 'wpforms_abilities_mask_ip_address', '__return_true' ) nel codice del tuo sito; una volta attivata questa opzione, gli indirizzi IPv4 vengono visualizzati con gli ultimi tre ottetti sostituiti da asterischi (ad esempio, ***.***.***.100).

wpforms/ricerca-voci

Cerca i dati in un singolo modulo o in tutti i moduli utilizzando filtri per testo completo, specifici per campo, stato e intervallo di date. Solo versione Pro.

Parametri

Esempio di richiesta

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"

Esempio di risposta

{
  "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 i clienti MCP

Ogni funzionalità di WPForms è registrata presso mcp.public impostare su true, il che significa che i client di IA compatibili con MCP (Claude Desktop, Cursor e altri) li rilevano automaticamente una volta che il sito WordPress è collegato tramite il wordpress/adattatore-mcp plugin. Una volta installato, non è necessaria alcuna ulteriore configurazione da parte di WPForms; le funzionalità compaiono nell'elenco degli strumenti del cliente sotto la voce WPForms categoria e rispettare gli stessi callback di autorizzazione utilizzati dall'API REST.

Individuare le capacità attraverso la programmazione

Per elencare le funzionalità disponibili su un sito invece di inserire i loro ID in modo statico:

# Elenca tutte le funzionalità registrate sul sito
curl "$WP_SITE/wp-json/wp-abilities/v1/abilities"

# Recupera lo schema di una singola funzionalità
curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/list-forms"

La risposta include l'ID, l'etichetta, la descrizione e la categoria di ciascuna funzionalità, oltre agli schemi completi di input e output: si tratta di informazioni sufficienti per sviluppare un client generico senza conoscere in anticipo l'interfaccia specifica di WPForms.

Link correlati

• Presentazione dell'API Abilities di WordPress (developer.wordpress.org)
• wordpress/mcp-adapter su GitHub
• Protocollo di contesto del modello