Referência da API REST do WPForms e da API do Abilities

A versão 1.9.9 do WPForms introduziu uma API REST de leitura apenas, desenvolvida com base na API Abilities do WordPress. É possível listar formulários, obter a configuração dos formulários, recuperar e pesquisar entradas, bem como aceder a estatísticas dos formulários a partir de qualquer cliente HTTP, da linha de comandos, do seu próprio código PHP ou de assistentes de IA que utilizem o Protocolo de Contexto de Modelo (MCP).

Se procurou por «WPForms REST API» e chegou até aqui, é isto mesmo. Não existe uma API REST separada; a integração com a API da Abilities é a forma como o WPForms disponibiliza os seus dados através de HTTP.

O que é a API Abilities

A API de Capacidades é uma funcionalidade do núcleo do WordPress adicionada na versão 6.9. Permite que os plugins declarem capacidades individuais (denominadas competências) com um nome, um esquema de entrada, um esquema de saída e uma função de retorno de permissão. O WordPress expõe então automaticamente todas as capacidades registadas através da API REST em /wp-json/wp-abilities/v1/abilities/<ability>/run e para clientes de IA compatíveis com o MCP através do plugin adaptador oficial do MCP.

O WPForms regista um conjunto de capacidades de leitura apenas sob o wpforms/ namespace. Cada funcionalidade executa as mesmas verificações de direitos do WPForms utilizadas no painel de administração (wpforms_current_user_can()), pelo que as interfaces REST e MCP herdam o modelo de permissões existente, em vez de introduzirem um novo.

Ativar uma habilidade

Cada função pode ser invocada através de dois mecanismos. O resultado é idêntico; escolha aquele que melhor se adequar ao ambiente de execução.

API REST

Enviar um GET solicitar /wp-json/wp-abilities/v1/abilities/<ability>/run. Como todas as funcionalidades do WPForms são de leitura apenas, apenas GET é aceite; POST retornos 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

A partir de qualquer plugin, tema ou código personalizado que seja executado após o wp_abilities_api_init A ação foi disparada, recuperar a habilidade com wp_get_ability() e chamar-lhe execute() método. Passe os dados de entrada como uma matriz associativa de parâmetros (com os mesmos nomes indicados na tabela de parâmetros de cada habilidade).

$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)
}

Autenticação

O transporte REST utiliza a autenticação padrão do WordPress. O método recomendado para clientes externos são as «senhas de aplicação», que estão integradas no núcleo do WordPress e não requerem qualquer plugin adicional.

Criar uma palavra-passe de aplicação

1. Inicie sessão como o utilizador do WordPress com as permissões sob as quais as chamadas devem ser executadas.
2. Vá a Utilizadores » Perfil e desça até à secção «Palavras-passe de aplicações ».
3. Introduza um nome para a integração e clique em «Adicionar nova palavra-passe da aplicação».
4. Copie a palavra-passe gerada. O WordPress só a mostra uma vez.

Para obter mais informações, incluindo pontos de extremidade REST para gerir senhas de aplicações por meio de programação, consulte o Guia de Integração de Senhas de Aplicações da equipa principal do WordPress.

Envio das credenciais

Envie o nome de utilizador e a palavra-passe da aplicação como autenticação HTTP básica em cada pedido.

Com o curl

Defina o URL do seu site como uma variável de ambiente para que os exemplos neste documento possam ser executados tal como estão:

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

Em seguida, adicione o -u Adicione esta opção a todos os comandos curl. O valor da opção é o seu nome de utilizador, seguido de dois pontos e, em seguida, da sua palavra-passe da aplicação (sem espaços).

Com o Postman, o Insomnia ou outros clientes

Defina o tipo de autenticação do pedido como «Basic Auth» e introduza o seu nome de utilizador e a palavra-passe da aplicação. O cliente trata da codificação por si.

Definir o cabeçalho manualmente

Envie as suas credenciais codificadas em base64 Authorization título:

Junte o seu nome de utilizador e a palavra-passe da aplicação numa única sequência, separados por dois pontos (sem espaços), e codifique o resultado em base64 utilizando uma ferramenta à sua escolha (base64 comando, um codificador online ou a biblioteca padrão da sua linguagem). Envie o valor codificado em cada pedido como o Authorization cabeçalho, no formato Authorization: Basic <encoded>.

Os exemplos de pedidos apresentados no resto deste documento omitem o sinalizador de autenticação para facilitar a leitura. Adicione o -u sinalizador (ou o Authorization (cabeçalho) a cada pedido válido, caso contrário a API devolve 401 Unauthorized.

Permissões

Cada função verifica uma funcionalidade específica do WPForms antes de ser executada. As verificações com falha devolvem um WP_Error com o código de estado HTTP 403.

Referência de habilidades

Todas as funções são de leitura e idempotentes. Os erros são devolvidos como WP_Error objetos serializados para JSON com code, messagee data.status campos.

wpforms/lista-de-formulários

Formulários de lista com metadados resumidos. Disponível nas versões Lite e Pro.

Parâmetros

Exemplo de pedido

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

Exemplo de resposta

{
  "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/obter-formulário

Recuperar um único formulário, incluindo um subconjunto selecionado das suas definições e, opcionalmente, a configuração dos seus campos. Disponível nas versões Lite e Pro.

Parâmetros

Exemplo de pedido

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

Exemplo de resposta

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

O settings O objeto devolvido por esta funcionalidade é um subconjunto selecionado e não confidencial (título, descrição, texto de envio, indicador de envio AJAX, honeypot, antispam). As definições de notificação, confirmação e integração não são divulgadas.

wpforms/obter-estatísticas-do-formulário

Estatísticas de envio de respostas para um formulário. O formato da resposta difere entre as versões Lite e Pro.

Parâmetros

Exemplo de pedido

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

Resposta simplificada

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

Resposta profissional

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

wpforms/obter-resumos-das-entradas

Lista paginada de resumos de entradas para um único formulário. Apenas na versão Pro.

Parâmetros

Exemplo de pedido

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"

Exemplo de resposta

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

Recuperar uma única entrada pelo ID, incluindo todos os valores dos campos. Apenas na versão Pro.

Parâmetros

Exemplo de pedido

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

Exemplo de resposta

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

O endereço IP na resposta pode ser ocultado. Adicionar add_filter( 'wpforms_abilities_mask_ip_address', '__return_true' ) no código do seu site; quando ativada, os endereços IPv4 aparecem com os últimos três octetos substituídos por asteriscos (por exemplo, ***.***.***.100).

wpforms/pesquisar-entradas

Pesquise entradas num único formulário ou em todos os formulários utilizando filtros de texto completo, específicos por campo, de estado e de intervalo de datas. Exclusivo da versão Pro.

Parâmetros

Exemplo de pedido

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"

Exemplo de resposta

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

Utilização do WPForms com clientes da MCP

Todas as funcionalidades do WPForms estão registadas em mcp.public definido para true, o que significa que os clientes de IA compatíveis com MCP (Claude Desktop, Cursor e outros) os detetam automaticamente assim que o site WordPress estiver ligado através do wordpress/adaptador-mcp plugin. Após a instalação, não é necessária qualquer configuração adicional no WPForms; as funcionalidades aparecem na lista de ferramentas do cliente, na secção WPForms categoria e respeitar os mesmos callbacks de permissão utilizados pela API REST.

Descobrir capacidades através da programação

Para listar as funcionalidades disponíveis num site, em vez de codificar manualmente os seus IDs:

# Listar todas as funcionalidades registadas no site
curl "$WP_SITE/wp-json/wp-abilities/v1/abilities"

# Obter o esquema de uma única funcionalidade
curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/list-forms"

A resposta inclui o ID, o rótulo, a descrição e a categoria de cada funcionalidade, bem como os esquemas completos de entrada e saída, o que constitui informação suficiente para criar um cliente genérico sem conhecimento prévio da interface específica do WPForms.

Links relacionados

• Apresentamos a API de Capacidades do WordPress (developer.wordpress.org)
• wordpress/mcp-adapter no GitHub
• Protocolo de Contexto do Modelo