Referência da API REST do WPForms e da API de Habilidades

O WPForms 1.9.9 introduziu uma API REST somente leitura, construída sobre a API de Habilidades do WordPress. Pode listar formulários, obter a configuração do formulário, recuperar e pesquisar entradas, e extrair estatísticas de formulários de qualquer cliente HTTP, da linha de comando, do seu próprio código PHP, ou de assistentes de IA que falem o Protocolo de Contexto do Modelo (MCP).

Se procurou por “WPForms REST API” e chegou aqui, é isto. Não existe uma API REST separada; a integração da API de Habilidades é como o WPForms expõe os seus dados via HTTP.

O que é a API de Habilidades

A API de Habilidades é uma funcionalidade principal do WordPress adicionada no WordPress 6.9. Permite que plugins declarem capacidades individuais (chamadas habilidades) 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 cada habilidade registada automaticamente através da API REST em /wp-json/wp-abilities/v1/abilities/<ability>/run e para clientes de IA compatíveis com MCP através do plugin oficial de adaptador MCP.

O WPForms regista um conjunto de habilidades somente leitura sob o namespace wpforms/. Cada habilidade executa as mesmas verificações de capacidade do WPForms usadas no admin (wpforms_current_user_can()), pelo que as superfícies REST e MCP herdam o modelo de permissão existente em vez de introduzir um novo.

Chamar uma Habilidade

Cada habilidade pode ser invocada através de dois transportes. O resultado é idêntico; escolha o que melhor se adapta ao ambiente de chamada.

API REST

Envie um pedido GET autenticado para /wp-json/wp-abilities/v1/abilities/<ability>/run. Como cada habilidade do WPForms é somente leitura, apenas GET é aceite; POST retorna 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

De qualquer plugin, tema ou código personalizado que seja executado após a ação wp_abilities_api_init ter sido disparada, obtenha a habilidade com wp_get_ability() e chame o seu método execute(). Passe a entrada como um array associativo de parâmetros (os mesmos nomes listados 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 usa 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 nenhum plugin adicional.

Gerar uma Senha de Aplicação

1. Inicie sessão como o utilizador do WordPress cujas permissões os pedidos devem ser executados.
2. Vá a Utilizadores » Perfil e navegue até à secção Senhas de Aplicação.
3. Introduza um nome para a integração e clique em Adicionar Nova Palavra-passe de Aplicação.
4. Copie a palavra-passe gerada. O WordPress só a mostra uma vez.

Para uma referência mais aprofundada, incluindo os pontos finais REST para gerir palavras-passe de aplicações programaticamente, consulte o Guia de Integração de Palavras-passe de Aplicações da equipa principal do WordPress.

Envio das Credenciais

Passe o nome de utilizador e a palavra-passe da aplicação como autenticação HTTP Basic em todos os pedidos.

Com o curl

Defina o URL do seu site como uma variável de ambiente para que os exemplos nesta documentação possam ser executados como estão:

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

Em seguida, adicione o sinalizador -u a todos os comandos curl. O valor do sinalizador é o seu nome de utilizador, seguido por dois pontos, seguido pela sua palavra-passe de aplicação (sem espaços).

Com Postman, Insomnia ou outros clientes

Defina o tipo de Autenticação do pedido para Basic Auth e forneça o seu nome de utilizador e palavra-passe de aplicação. O cliente trata da codificação por si.

Definição manual do cabeçalho

Envie as suas credenciais como um cabeçalho Authorization codificado em base64:

Combine o seu nome de utilizador e palavra-passe de aplicação numa única string, separada por dois pontos (sem espaços), e codifique o resultado em base64 usando uma ferramenta à sua escolha (comando base64, um codificador online ou a biblioteca padrão da sua linguagem). Envie o valor codificado em todos os pedidos como o cabeçalho Authorization, na forma Authorization: Basic <codificado>.

Os exemplos de pedidos no resto desta documentação omitem o sinalizador de autenticação para facilitar a leitura. Adicione o sinalizador -u (ou o cabeçalho Authorization) a todos os pedidos reais, ou a API retornará 401 Unauthorized.

Permissões

Cada capacidade verifica uma capacidade específica do WPForms antes de executar. As verificações falhadas retornam um WP_Error com o estado HTTP 403.

Referência de Habilidade

Todas as habilidades são somente leitura e idempotentes. Erros são retornados como objetos WP_Error serializados para JSON com os campos code, message e data.status.

wpforms/list-forms

Listar formulários com metadados de resumo. Disponível em Lite e Pro.

Parâmetros

Pedido de Exemplo

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

Resposta de Exemplo

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

Recuperar um único formulário, incluindo um subconjunto selecionado de suas configurações e, opcionalmente, sua configuração de campo. Disponível em Lite e Pro.

Parâmetros

Pedido de Exemplo

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

Resposta de Exemplo

{
  "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 objeto settings retornado por esta habilidade é um subconjunto selecionado e não sensível (título, descrição, texto de envio, sinalizador de envio AJAX, honeypot, anti-spam). As configurações de notificação, confirmação e integração não são expostas.

wpforms/get-form-stats

Retornar estatísticas de submissão para um formulário. A forma da resposta difere entre Lite e Pro.

Parâmetros

Pedido de Exemplo

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

Resposta Lite

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

Resposta Pro

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

wpforms/get-entry-summaries

Lista paginada de resumos de entradas para um único formulário. Apenas Pro.

Parâmetros

Pedido de Exemplo

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"

Resposta de Exemplo

{
  "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 por ID, incluindo todos os valores de campo. Apenas Pro.

Parâmetros

Pedido de Exemplo

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

Resposta de Exemplo

{
  "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 mascarado. Adicione add_filter( 'wpforms_abilities_mask_ip_address', '__return_true' ) ao código do seu site; quando ativado, os endereços IPv4 aparecem com os seus últimos três octetos substituídos por asteriscos (por exemplo, ***.***.***.100).

wpforms/search-entries

Pesquisar entradas em um ou todos os formulários com filtros de texto completo, específicos de campo, de status e de intervalo de datas. Apenas Pro.

Parâmetros

Pedido de Exemplo

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"

Resposta de Exemplo

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

Utilizar WPForms com Clientes MCP

Todas as capacidades do WPForms são registadas com mcp.public definido como true, o que significa que os clientes de IA compatíveis com MCP (Claude Desktop, Cursor e outros) descobrem-nas automaticamente assim que o site WordPress é conectado através do plugin wordpress/mcp-adapter. Após a instalação, não é necessária mais nenhuma configuração do lado do WPForms; as capacidades aparecem na lista de ferramentas do cliente sob a categoria WPForms e respeitam as mesmas callbacks de permissão usadas pela API REST.

Descobrir Capacidades Programaticamente

Para enumerar as capacidades disponíveis num site em vez de codificar os seus IDs:

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

A resposta inclui o ID, rótulo, descrição, categoria e os esquemas de entrada e saída completos de cada capacidade, o que é informação suficiente para construir um cliente genérico sem conhecimento prévio da superfície específica do WPForms.

Ligações Relacionadas

• Apresentação da API de Capacidades do WordPress (developer.wordpress.org)
• wordpress/mcp-adapter no GitHub
• Protocolo de Contexto do Modelo