WPForms REST API e Riferimenti API Abilities

WPForms 1.9.9 ha introdotto un'API REST basata sull'API Abilities di WordPress, e WPForms 1.10.2 l'ha espansa con supporto di scrittura opt-in. Puoi elencare moduli, recuperare la configurazione dei moduli, recuperare e cercare voci, e ottenere statistiche dei moduli, e, una volta abilitato l'accesso in scrittura, creare moduli, aggiungere e aggiornare campi, e aggiornare impostazioni sicure dei moduli. Ogni abilità funziona 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 abilità sotto lo spazio dei nomi wpforms/. Le abilità di lettura sono disponibili da WPForms 1.9.9. WPForms 1.10.2 ha aggiunto un set di abilità di scrittura che sono disabilitate per impostazione predefinita (vedi Abilitazione dell'accesso in scrittura sotto). Ogni abilità esegue gli stessi controlli di capacità di WPForms utilizzati nell'amministrazione (wpforms_current_user_can()), quindi le superfici REST e MCP ereditano il modello di autorizzazione 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 autenticata a /wp-json/wp-abilities/v1/abilities/<ability>/run. Il metodo HTTP dipende dall'abilità: le abilità di lettura usano GET, e le abilità di scrittura usano POST. Chiamare un'abilità con il metodo errato 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.

Abilitazione dell'accesso in scrittura

Le abilità di lettura sono sempre disponibili. Le abilità di scrittura (wpforms/create-form, wpforms/add-field, wpforms/update-field e wpforms/update-form-settings) sono disabilitate per impostazione predefinita e devono essere attivate prima che vengano eseguite. Ci sono due modi per attivarle, e il filtro ha sempre l'ultima parola.

Abilitazione delle scritture nel codice

Abilita le scritture programmaticamente con il filtro wpforms_integrations_abilities_allow_write:

add_filter( 'wpforms_integrations_abilities_allow_write', '__return_true' );

Il filtro sovrascrive il toggle senza codice in entrambe le direzioni. Restituire true abilita le scritture anche quando il toggle è disattivato, e restituire false le disabilita anche quando il toggle è attivato. Questo mantiene invariati gli attuali setup degli sviluppatori.

Abilitazione delle scritture senza codice

I proprietari del sito possono abilitare le scritture da WPForms » Strumenti » AI MCP con l'interruttore Abilita accesso in scrittura MCP, che persiste nella chiave ai-mcp-write-enabled nell'opzione wpforms_settings. Il filtro sopra ha la precedenza su questo interruttore. Per la guida completa, vedere Utilizzo di WPForms con assistenti AI.

Permessi

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

Le funzionalità di scrittura aggiunte in WPForms 1.10.2 applicano lo stesso modello di capacità. wpforms/create-form richiede la capacità di creare moduli, e wpforms/add-field, wpforms/update-field e wpforms/update-form-settings richiedono la capacità di modificare il modulo di destinazione. Un controllo fallito restituisce un WP_Error con stato HTTP 403. Le funzionalità di scrittura richiedono anche che l'accesso in scrittura sia abilitato, come descritto sopra.

Riferimento abilità

Le funzionalità di lettura sono idempotenti e sicure da chiamare ripetutamente. Le funzionalità di scrittura, aggiunte in WPForms 1.10.2, creano o modificano dati del modulo e richiedono che l'accesso in scrittura sia prima abilitato. Gli errori vengono restituiti come oggetti WP_Error serializzati in JSON con 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
}

Le funzionalità seguenti sono state aggiunte in WPForms 1.10.2. Tutte richiedono che l'accesso in scrittura sia abilitato (vedere Abilitazione dell'accesso in scrittura), ad eccezione di wpforms/describe-editing-schema, che è una funzionalità di lettura utilizzata per scoprire cosa accettano le funzionalità di scrittura. Le funzionalità di scrittura vengono eseguite come richieste POST su REST, o tramite execute() in PHP.

wpforms/describe-editing-schema

Restituisce i tipi di campo e le impostazioni del modulo che le funzionalità di scrittura accettano su questo sito. Chiamare prima questa funzione, poiché i tipi di campo disponibili dipendono dal livello di licenza. Disponibile in Lite e Pro.

Richiesta di esempio

curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/describe-editing-schema/run?input%5B%5D="

Esempio di risposta (troncato)

{
  "field_types": [
    {
      "type": "text",
      "label": "Single Line Text",
      "properties": [
        { "key": "label",         "schema": { "type": "string" } },
        { "key": "required",      "schema": { "type": "boolean" } },
        { "key": "size",          "schema": { "type": "string", "enum": ["small", "medium", "large"] } },
        { "key": "placeholder",   "schema": { "type": "string" } },
        { "key": "default_value", "schema": { "type": "string" } }
      ],
      "required_props": []
    },
    {
      "type": "select",
      "label": "Dropdown",
      "properties": [
        { "key": "choices", "schema": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": ["label"] } } },
        { "key": "style",   "schema": { "type": "string", "enum": ["classic", "modern"] } }
      ],
      "required_props": []
    }
  ],
  "form_settings": [
    { "key": "form_title",  "schema": { "type": "string" }, "description": "The form title." },
    { "key": "form_desc",   "schema": { "type": "string" }, "description": "The form description." },
    { "key": "submit_text", "schema": { "type": "string" }, "description": "The submit button label." }
  ]
}

Su Pro, field_types elenca text, textarea, email, number, select, radio, checkbox, name, phone, date-time e file-upload. Su Lite, l'insieme è costituito dagli otto tipi base: text, textarea, email, number, select, radio, checkbox e name. Gli slug corrispondono al builder, quindi il campo Dropdown è select e il campo Date / Time è date-time.

Proprietà del campo

Le capacità create-form, add-field e update-field accettano queste proprietà del campo. Ogni proprietà si applica solo ai tipi di campo che la dichiarano, come riportato da describe-editing-schema.

wpforms/crea-modulo

Crea un nuovo modulo con un set opzionale di campi e impostazioni, in una singola chiamata. Disponibile in Lite e Pro.

Parametri

Richiesta di esempio

$ability = wp_get_ability( 'wpforms/create-form' );

$result = $ability->execute(
    [
        'title'  => 'Job Application',
        'fields' => [
            [ 'type' => 'name',   'label' => 'Your Name', 'required' => true ],
            [ 'type' => 'email',  'label' => 'Email',      'required' => true ],
            [ 'type' => 'select', 'label' => 'Position',   'choices' => [ [ 'label' => 'Baker' ], [ 'label' => 'Cashier' ] ] ],
        ],
        'settings' => [
            'form_title'  => 'Job Application',
            'form_desc'   => 'Apply to join our team.',
            'submit_text' => 'Apply Now',
        ],
    ]
);

Risposta di esempio

{
  "form_id": 1102,
  "fields": [
    { "id": 0, "type": "name" },
    { "id": 1, "type": "email" },
    { "id": 2, "type": "select" }
  ]
}

wpforms/aggiungi-campo

Aggiungi un nuovo campo a un modulo esistente. Disponibile in Lite e Pro.

Parametri

Passa le proprietà del campo per il tipo scelto insieme a form_id e type (vedi la tabella Proprietà del campo sopra).

Richiesta di esempio

$ability = wp_get_ability( 'wpforms/add-field' );

$result = $ability->execute(
    [
        'form_id'  => 1102,
        'type'     => 'phone',
        'label'    => 'Phone',
        'required' => true,
    ]
);

Risposta di esempio

{
  "form_id": 1102,
  "field_id": 6,
  "type": "phone"
}

wpforms/aggiorna-campo

Aggiorna le proprietà di un campo esistente. Disponibile in Lite e Pro.

Parametri

Passa le proprietà del campo che desideri modificare insieme a form_id e field_id (vedi la tabella Proprietà del campo sopra). Le proprietà omesse rimangono invariate. Quando invii choices, la nuova lista viene unita per indice alle scelte esistenti.

Richiesta di esempio

$ability = wp_get_ability( 'wpforms/update-field' );

$result = $ability->execute(
    [
        'form_id'     => 1102,
        'field_id'    => 6,
        'required'    => true,
        'placeholder' => 'e.g. 555-123-4567',
    ]
);

Risposta di esempio

{
  "form_id": 1102,
  "field_id": 6,
  "updated": ["required", "placeholder"],
  "ignored": []
}

wpforms/aggiorna-impostazioni-modulo

Aggiorna le impostazioni sicure di un modulo. La whitelist v1 è form_title, form_desc e submit_text. Disponibile in Lite e Pro.

Parametri

Richiesta di esempio

$ability = wp_get_ability( 'wpforms/update-form-settings' );

$result = $ability->execute(
    [
        'form_id'  => 1102,
        'settings' => [
            'submit_text' => 'Send Application',
        ],
    ]
);

Risposta di esempio

{
  "form_id": 1102,
  "updated": ["submit_text"],
  "ignored": []
}

Le chiavi che non sono nella whitelist vengono restituite nell'array ignored anzich uevo causare un errore. Ad esempio, l'invio di ajax_submit lo lascia invariato e lo elenca sotto ignored.

Utilizzo di WPForms con Client MCP

Le abilit uevo di lettura sono registrate con mcp.public impostato su true, quindi i client AI compatibili con MCP (Claude Desktop, Cursor e altri) le scoprono automaticamente una volta che il sito WordPress uevo connesso tramite il plugin wordpress/mcp-adapter. Le abilit uevo di scrittura e wpforms/describe-editing-schema sono esposte a MCP solo quando l'accesso in scrittura uevo abilitato; mentre le scritture sono disattivate, il loro flag mcp.public uevo false e sono nascoste alla scoperta di MCP, quindi un assistente potrebbe segnalare di non riuscire a trovare gli strumenti di scrittura di WPForms. Una volta che un sito uevo connesso e l'accesso in scrittura uevo attivo, le abilit uevo 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.

Le abilit uevo di scrittura appaiono in questo indice su qualsiasi sito che esegue WPForms 1.10.2 o versioni successive, indipendentemente dal fatto che l'accesso in scrittura sia abilitato o meno. Il loro flag mcp.public riflette lo stato dell'accesso in scrittura, tuttavia: uevo true solo quando le scritture sono abilitate, motivo per cui i client MCP vedono gli strumenti di scrittura solo dopo che l'accesso in scrittura uevo attivato.

Estensione del registro dei campi

I tipi di campo e le propriet uevo che le abilit uevo di scrittura accettano sono definiti in un registro estensibile. Gli addon possono registrare i propri tipi di campo e propriet uevo tramite due filtri, in modo che un tipo di campo personalizzato o di addon possa diventare disponibile per create-form, add-field e update-field.

• wpforms_integrations_abilities_field_registry_types registra nuovi tipi di campo. Ogni tipo dichiara la propria disponibilit uevo tramite un valore requires, che uevo la stringa pro, un slug di addon o una funzione richiamabile, e pu uevo specificare le sue propriet uevo richieste.
• wpforms_integrations_abilities_field_registry_properties contribuisce con nuove definizioni di propriet uevo a cui i tipi di campo possono fare riferimento.

add_filter(
    'wpforms_integrations_abilities_field_registry_types',
    function ( $types ) {
        // Register one or more field types here, then return the list.
        return $types;
    }
);

Link Correlati

• Utilizzo di WPForms con assistenti AI, la guida no-code per connettere un assistente AI
• Introduzione all'API delle Funzionalità di WordPress (developer.wordpress.org)
• wordpress/mcp-adapter su GitHub
• Protocollo di Contesto del Modello