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

O WPForms 1.9.9 introduziu uma API REST construída sobre a API de Habilidades do WordPress, e o WPForms 1.10.2 expandiu-a com suporte de escrita opcional. Pode listar formulários, obter a configuração do formulário, recuperar e pesquisar entradas, e obter estatísticas do formulário, e, uma vez ativado o acesso de escrita, criar formulários, adicionar e atualizar campos, e atualizar configurações seguras do formulário. Cada habilidade funciona a partir 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 sob o namespace wpforms/. As habilidades de leitura estão disponíveis desde o WPForms 1.9.9. O WPForms 1.10.2 adicionou um conjunto de habilidades de escrita que estão desativadas por defeito (ver Ativar Acesso de Escrita abaixo). Cada habilidade executa as mesmas verificações de capacidade do WPForms usadas na administração (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 autenticado para /wp-json/wp-abilities/v1/abilities/<ability>/run. O método HTTP depende da habilidade: as habilidades de leitura usam GET, e as habilidades de escrita usam POST. Chamar uma habilidade com o método errado 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.

Ativar Acesso de Escrita

As habilidades de leitura estão sempre disponíveis. As habilidades de escrita (wpforms/create-form, wpforms/add-field, wpforms/update-field, e wpforms/update-form-settings) estão desativadas por defeito e devem ser ativadas antes de serem executadas. Existem duas formas de as ativar, e o filtro tem sempre a palavra final.

Ativar Escritas em Código

Ative as escritas programaticamente com o filtro wpforms_integrations_abilities_allow_write:

add_filter( 'wpforms_integrations_abilities_allow_write', '__return_true' );

O filtro substitui o interruptor sem código em ambas as direções. Retornar true ativa as escritas mesmo quando o interruptor está desligado, e retornar false desativa-as mesmo quando o interruptor está ligado. Isto mantém as configurações existentes dos programadores a funcionar sem alterações.

Ativar Escritas Sem Código

Os proprietários do site podem ativar gravações em WPForms » Ferramentas » AI MCP com o interruptor Ativar Acesso de Gravação MCP, que persiste na chave ai-mcp-write-enabled na opção wpforms_settings. O filtro acima tem precedência sobre este interruptor. Para o guia completo, consulte Usar WPForms Com Assistentes de IA.

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.

As capacidades de gravação adicionadas no WPForms 1.10.2 aplicam o mesmo modelo de capacidade. wpforms/create-form requer a capacidade de criar formulários, e wpforms/add-field, wpforms/update-field e wpforms/update-form-settings requerem a capacidade de editar o formulário de destino. Uma verificação falhada retorna um WP_Error com o status HTTP 403. As capacidades de gravação também requerem que o acesso de gravação esteja ativado, como descrito acima.

Referência de Habilidade

As capacidades de leitura são idempotentes e seguras para serem chamadas repetidamente. As capacidades de gravação, adicionadas no WPForms 1.10.2, criam ou modificam dados de formulário e requerem que o acesso de gravação seja ativado primeiro. 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
}

As capacidades abaixo foram adicionadas no WPForms 1.10.2. Todas elas requerem que o acesso de gravação esteja ativado (consulte Ativar Acesso de Gravação), exceto wpforms/describe-editing-schema, que é uma capacidade de leitura usada para descobrir o que as capacidades de gravação aceitam. As capacidades de gravação são executadas como requisições POST sobre REST, ou através de execute() em PHP.

wpforms/descrever-esquema-de-edição

Retorna os tipos de campo e as configurações de formulário que as capacidades de gravação aceitam neste site. Chame esta primeiro, pois os tipos de campo disponíveis dependem do nível da licença. Disponível em Lite e Pro.

Pedido de Exemplo

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

Resposta de Exemplo (truncada)

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

No Pro, field_types lista text, textarea, email, number, select, radio, checkbox, name, phone, date-time e file-upload. No Lite, o conjunto é o conjunto base de oito: text, textarea, email, number, select, radio, checkbox e name. Os slugs correspondem ao construtor, pelo que o campo Dropdown é select e o campo Date / Time é date-time.

Propriedades do Campo

As capacidades create-form, add-field e update-field aceitam estas propriedades de campo. Cada propriedade aplica-se apenas aos tipos de campo que a declaram, conforme relatado por describe-editing-schema.

wpforms/criar-formulario

Crie um novo formulário com um conjunto opcional de campos e definições, numa única chamada. Disponível em Lite e Pro.

Parâmetros

Pedido de Exemplo

$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',
        ],
    ]
);

Resposta de Exemplo

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

wpforms/adicionar-campo

Adicione um novo campo a um formulário existente. Disponível em Lite e Pro.

Parâmetros

Passe quaisquer propriedades de campo para o tipo escolhido juntamente com form_id e type (consulte a tabela Propriedades de Campo acima).

Pedido de Exemplo

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

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

Resposta de Exemplo

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

wpforms/atualizar-campo

Atualize as propriedades de um campo existente. Disponível em Lite e Pro.

Parâmetros

Passe as propriedades do campo que deseja alterar juntamente com form_id e field_id (consulte a tabela Propriedades de Campo acima). As propriedades que omitir permanecem inalteradas. Quando envia choices, a nova lista é mesclada por índice sobre as escolhas existentes.

Pedido de Exemplo

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

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

Resposta de Exemplo

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

wpforms/atualizar-definicoes-formulario

Atualize as definições seguras de um formulário. A lista branca v1 é form_title, form_desc e submit_text. Disponível em Lite e Pro.

Parâmetros

Pedido de Exemplo

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

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

Resposta de Exemplo

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

Chaves que não estão na lista de permissões são retornadas na matriz ignored em vez de causar um erro. Por exemplo, enviar ajax_submit deixa-o inalterado e lista-o em ignored.

Utilizar WPForms com Clientes MCP

As capacidades de leitura são registadas com mcp.public definido como true, pelo que os clientes de IA compatíveis com MCP (Claude Desktop, Cursor e outros) descobrem-nas automaticamente assim que o site WordPress é ligado através do plugin wordpress/mcp-adapter. As capacidades de escrita e wpforms/describe-editing-schema são expostas ao MCP apenas quando o acesso de escrita está ativado; enquanto as escritas estão desativadas, a sua bandeira mcp.public é false e são ocultadas da descoberta do MCP, pelo que um assistente pode relatar que não consegue encontrar as ferramentas de escrita do WPForms. Assim que um site é ligado e o acesso de escrita está ativado, as capacidades aparecem na lista de ferramentas do cliente sob a categoria WPForms e respeitam as mesmas chamadas 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.

As capacidades de escrita aparecem neste índice em qualquer site que execute o WPForms 1.10.2 ou posterior, independentemente de o acesso de escrita estar ativado ou não. A sua bandeira mcp.public reflete o estado de acesso de escrita, no entanto: é true apenas quando as escritas estão ativadas, que é a razão pela qual os clientes MCP veem as ferramentas de escrita apenas depois de o acesso de escrita ser ativado.

Estender o Registo de Campos

Os tipos de campo e propriedades que as capacidades de escrita aceitam são definidos num registo extensível. Addons podem registar os seus próprios tipos de campo e propriedades através de dois filtros, pelo que um tipo de campo personalizado ou de addon pode tornar-se disponível para create-form, add-field e update-field.

• wpforms_integrations_abilities_field_registry_types regista novos tipos de campo. Cada tipo declara a sua disponibilidade através de um valor requires, que é a string pro, um slug de addon, ou um callable, e pode especificar as suas propriedades necessárias.
• wpforms_integrations_abilities_field_registry_properties contribui com novas definições de propriedades que os tipos de campo podem referenciar.

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

Ligações Relacionadas

• Usar o WPForms Com Assistentes de IA, o guia sem código para ligar um assistente de IA
• Apresentação da API de Capacidades do WordPress (developer.wordpress.org)
• wordpress/mcp-adapter no GitHub
• Protocolo de Contexto do Modelo