Referencia de la API REST de WPForms y la API de Habilidades

WPForms 1.9.9 introdujo una API REST construida sobre la API de Habilidades de WordPress, y WPForms 1.10.2 la amplió con soporte de escritura opcional. Puede listar formularios, obtener la configuración del formulario, recuperar y buscar entradas, y extraer estadísticas del formulario, y, una vez habilitado el acceso de escritura, crear formularios, añadir y actualizar campos, y actualizar configuraciones seguras del formulario. Cada habilidad funciona desde cualquier cliente HTTP, la línea de comandos, su propio código PHP, o asistentes de IA que hablen el Protocolo de Contexto de Modelo (MCP).

Si buscaste "WPForms REST API" y llegaste aquí, esto es. No hay una API REST separada; la integración de la API de Habilidades *es* cómo WPForms expone sus datos a través de HTTP.

¿Qué es la API de Habilidades?

La API de Habilidades es una característica principal de WordPress añadida en WordPress 6.9. Permite a los plugins declarar capacidades individuales (llamadas *habilidades*) con un nombre, un esquema de entrada, un esquema de salida y una función de devolución de llamada de permiso. WordPress expone automáticamente cada habilidad registrada a través de la API REST en /wp-json/wp-abilities/v1/abilities/<ability>/run y a clientes de IA compatibles con MCP a través del plugin oficial de adaptador MCP.

WPForms registra un conjunto de habilidades bajo el espacio de nombres wpforms/. Las habilidades de lectura han estado disponibles desde WPForms 1.9.9. WPForms 1.10.2 añadió un conjunto de habilidades de escritura que están deshabilitadas por defecto (ver Habilitar acceso de escritura abajo). Cada habilidad ejecuta las mismas comprobaciones de capacidades de WPForms utilizadas en el administrador (wpforms_current_user_can()), por lo que las superficies REST y MCP heredan el modelo de permisos existente en lugar de introducir uno nuevo.

Llamar a una Habilidad

Cada habilidad se puede invocar a través de dos transportes. El resultado es idéntico; elige el que mejor se adapte al entorno de llamada.

API REST

Envía una solicitud autenticada a /wp-json/wp-abilities/v1/abilities/<ability>/run. El método HTTP depende de la habilidad: las habilidades de lectura usan GET, y las habilidades de escritura usan POST. Llamar a una habilidad con el método incorrecto devuelve 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

Desde cualquier plugin, tema o código personalizado que se ejecute después de que se haya activado la acción wp_abilities_api_init, obtén la habilidad con wp_get_ability() y llama a su método execute(). Pasa la entrada como un array asociativo de parámetros (los mismos nombres que se enumeran en la tabla de parámetros de cada habilidad).

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

Autenticación

El transporte REST utiliza la autenticación estándar de WordPress. El método recomendado para clientes externos son las Contraseñas de Aplicación, que están integradas en el núcleo de WordPress y no requieren ningún plugin adicional.

Generar una Contraseña de Aplicación

1. Inicia sesión como el usuario de WordPress bajo cuyas permisos se deben ejecutar las llamadas.
2. Ve a Usuarios » Perfil y desplázate hasta la sección Contraseñas de Aplicación.
3. Introduce un nombre para la integración y haz clic en Añadir nueva contraseña de aplicación.
4. Copia la contraseña generada. WordPress solo la muestra una vez.

Para una referencia más detallada, incluyendo los puntos finales REST para gestionar contraseñas de aplicación mediante programación, consulta la Guía de integración de contraseñas de aplicación del equipo principal de WordPress.

Envío de las credenciales

Pasa el nombre de usuario y la contraseña de la aplicación como autenticación HTTP Basic en cada solicitud.

Con curl

Establece la URL de tu sitio como una variable de entorno para que los ejemplos de esta documentación se puedan ejecutar tal cual:

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

Luego añade el indicador -u a cada comando curl. El valor del indicador es tu nombre de usuario, seguido de dos puntos, seguido de tu contraseña de aplicación (sin espacios).

Con Postman, Insomnia u otros clientes

Establece el tipo Auth de la solicitud en Basic Auth y proporciona tu nombre de usuario y contraseña de aplicación. El cliente se encarga de la codificación por ti.

Establecer la cabecera manualmente

Envía tus credenciales como una cabecera Authorization codificada en base64:

Combina tu nombre de usuario y contraseña de aplicación en una sola cadena, separada por dos puntos (sin espacios), y codifica el resultado en base64 usando una herramienta de tu elección (comando base64, un codificador en línea o la biblioteca estándar de tu lenguaje). Envía el valor codificado en cada solicitud como la cabecera Authorization, con el formato Authorization: Basic <encoded>.

Los ejemplos de solicitud en el resto de esta documentación omiten el indicador de autenticación por motivos de legibilidad. Añade el indicador -u (o la cabecera Authorization) a cada solicitud real, o la API devolverá 401 Unauthorized.

Habilitar acceso de escritura

Las habilidades de lectura están siempre disponibles. Las habilidades de escritura (wpforms/create-form, wpforms/add-field, wpforms/update-field y wpforms/update-form-settings) están deshabilitadas por defecto y deben activarse antes de que se ejecuten. Hay dos maneras de habilitarlas, y el filtro siempre tiene la última palabra.

Habilitar escrituras en código

Habilita escrituras programáticamente con el filtro wpforms_integrations_abilities_allow_write:

add_filter( 'wpforms_integrations_abilities_allow_write', '__return_true' );

El filtro anula el interruptor sin código en ambas direcciones. Devolver true habilita las escrituras incluso cuando el interruptor está apagado, y devolver false las deshabilita incluso cuando el interruptor está encendido. Esto mantiene los entornos de desarrollador existentes funcionando sin cambios.

Habilitar escrituras sin código

Los propietarios del sitio pueden habilitar escrituras desde WPForms » Herramientas » AI MCP con el interruptor Habilitar acceso de escritura de MCP, que persiste en la clave ai-mcp-write-enabled en la opción wpforms_settings. El filtro anterior tiene prioridad sobre este interruptor. Para el tutorial completo, consulta Uso de WPForms con asistentes de IA.

Permisos

Cada habilidad comprueba una capacidad específica de WPForms antes de ejecutarse. Las comprobaciones fallidas devuelven un WP_Error con el estado HTTP 403.

Las capacidades de escritura añadidas en WPForms 1.10.2 aplican el mismo modelo de capacidades. wpforms/create-form requiere la capacidad de crear formularios, y wpforms/add-field, wpforms/update-field y wpforms/update-form-settings requieren la capacidad de editar el formulario de destino. Una comprobación fallida devuelve un WP_Error con el estado HTTP 403. Las capacidades de escritura también requieren que el acceso de escritura esté habilitado, como se describe anteriormente.

Referencia de Habilidad

Las capacidades de lectura son idempotentes y seguras de llamar repetidamente. Las capacidades de escritura, añadidas en WPForms 1.10.2, crean o modifican datos de formularios y requieren que el acceso de escritura esté habilitado primero. Los errores se devuelven como objetos WP_Error serializados a JSON con los campos code, message y data.status.

wpforms/list-forms

Enumera formularios con metadatos resumidos. Disponible en Lite y Pro.

Parámetros

Solicitud de ejemplo

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

Respuesta de ejemplo

{
  "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 solo formulario, incluyendo un subconjunto curado de su configuración y, opcionalmente, su configuración de campos. Disponible en Lite y Pro.

Parámetros

Solicitud de ejemplo

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

Respuesta de ejemplo

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

El objeto settings devuelto por esta habilidad es un subconjunto curado y no sensible (título, descripción, texto de envío, indicador de envío AJAX, honeypot, anti-spam). La configuración de notificación, confirmación e integración no se expone.

wpforms/get-form-stats

Devuelve estadísticas de envíos para un formulario. La forma de la respuesta difiere entre Lite y Pro.

Parámetros

Solicitud de ejemplo

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

Respuesta Lite

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

Respuesta Pro

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

wpforms/get-entry-summaries

Lista paginada de resúmenes de entradas para un solo formulario. Solo Pro.

Parámetros

Solicitud de ejemplo

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"

Respuesta de ejemplo

{
  "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 una única entrada por ID, incluyendo todos los valores de los campos. Solo Pro.

Parámetros

Solicitud de ejemplo

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

Respuesta de ejemplo

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

La dirección IP en la respuesta puede ser enmascarada. Añada add_filter( 'wpforms_abilities_mask_ip_address', '__return_true' ) al código de su sitio; cuando esté habilitado, las direcciones IPv4 aparecerán con sus últimos tres octetos reemplazados por asteriscos (por ejemplo, ***.***.***.100).

wpforms/search-entries

Buscar entradas en un formulario o en todos los formularios con filtros de texto completo, específicos de campo, de estado y de rango de fechas. Solo Pro.

Parámetros

Solicitud de ejemplo

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"

Respuesta de ejemplo

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

Las capacidades a continuación se añadieron en WPForms 1.10.2. Todas ellas requieren que el acceso de escritura esté habilitado (ver Habilitar acceso de escritura), excepto wpforms/describe-editing-schema, que es una capacidad de lectura utilizada para descubrir qué aceptan las capacidades de escritura. Las capacidades de escritura se ejecutan como solicitudes POST sobre REST, o a través de execute() en PHP.

wpforms/describe-editing-schema

Devuelve los tipos de campo y la configuración del formulario que las capacidades de escritura aceptan en este sitio. Llama a esto primero, ya que los tipos de campo disponibles dependen del nivel de licencia. Disponible en Lite y Pro.

Solicitud de ejemplo

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

Respuesta de ejemplo (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." }
  ]
}

En Pro, field_types lista text, textarea, email, number, select, radio, checkbox, name, phone, date-time y file-upload. En Lite, el conjunto son los ocho básicos: text, textarea, email, number, select, radio, checkbox y name. Las claves coinciden con el constructor, por lo que el campo Dropdown es select y el campo Date / Time es date-time.

Propiedades del campo

Las habilidades create-form, add-field y update-field aceptan estas propiedades de campo. Cada propiedad se aplica solo a los tipos de campo que la declaran, según lo informado por describe-editing-schema.

wpforms/crear-formulario

Crea un nuevo formulario con un conjunto opcional de campos y configuraciones, en una sola llamada. Disponible en Lite y Pro.

Parámetros

Solicitud de ejemplo

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

Respuesta de ejemplo

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

wpforms/agregar-campo

Agrega un nuevo campo a un formulario existente. Disponible en Lite y Pro.

Parámetros

Pasa las propiedades del campo para el tipo elegido junto con form_id y type (consulta la tabla de Propiedades de Campo anterior).

Solicitud de ejemplo

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

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

Respuesta de ejemplo

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

wpforms/actualizar-campo

Actualiza las propiedades de un campo existente. Disponible en Lite y Pro.

Parámetros

Pasa las propiedades del campo que deseas cambiar junto con form_id y field_id (consulta la tabla de Propiedades de Campo anterior). Las propiedades que omites se dejan sin cambios. Cuando envías choices, la nueva lista se fusiona por índice sobre las opciones existentes.

Solicitud de ejemplo

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

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

Respuesta de ejemplo

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

wpforms/actualizar-configuraciones-formulario

Actualiza las configuraciones seguras de un formulario. La lista blanca de la v1 es form_title, form_desc y submit_text. Disponible en Lite y Pro.

Parámetros

Solicitud de ejemplo

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

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

Respuesta de ejemplo

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

Las claves que no están en la lista blanca se devuelven en la matriz ignored en lugar de causar un error. Por ejemplo, enviar ajax_submit lo deja sin cambios y lo lista bajo ignored.

Uso de WPForms con clientes MCP

Las capacidades de lectura se registran con mcp.public establecido en true, por lo que los clientes de IA compatibles con MCP (Claude Desktop, Cursor y otros) las descubren automáticamente una vez que el sitio de WordPress se conecta a través del plugin wordpress/mcp-adapter. Las capacidades de escritura y wpforms/describe-editing-schema se exponen a MCP solo cuando el acceso de escritura está habilitado; mientras las escrituras están desactivadas, su indicador mcp.public es false y se ocultan del descubrimiento de MCP, por lo que un asistente puede informar que no puede encontrar las herramientas de escritura de WPForms. Una vez que un sitio está conectado y el acceso de escritura está activado, las capacidades aparecen en la lista de herramientas del cliente bajo la categoría WPForms y respetan las mismas devoluciones de llamada de permisos utilizadas por la API REST.

Descubrimiento de capacidades mediante programación

Para enumerar las capacidades disponibles en un sitio en lugar de codificar sus 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 respuesta incluye el ID, la etiqueta, la descripción, la categoría y los esquemas de entrada y salida completos de cada capacidad, lo que es suficiente información para crear un cliente genérico sin conocimiento previo de la superficie específica de WPForms.

Las capacidades de escritura aparecen en este índice en cualquier sitio que ejecute WPForms 1.10.2 o posterior, independientemente de si el acceso de escritura está habilitado o no. Su indicador mcp.public refleja el estado de acceso de escritura; sin embargo, es true solo cuando las escrituras están habilitadas, razón por la cual los clientes de MCP ven las herramientas de escritura solo después de que se activa el acceso de escritura.

Ampliación del registro de campos

Los tipos de campos y propiedades que aceptan las capacidades de escritura se definen en un registro extensible. Los complementos pueden registrar sus propios tipos y propiedades de campo a través de dos filtros, por lo que un tipo de campo personalizado o de complemento puede estar disponible para create-form, add-field y update-field.

• wpforms_integrations_abilities_field_registry_types registra nuevos tipos de campo. Cada tipo declara su disponibilidad a través de un valor requires, que es la cadena pro, el slug de un complemento o una función invocable, y puede especificar sus propiedades requeridas.
• wpforms_integrations_abilities_field_registry_properties contribuye con nuevas definiciones de propiedades que los tipos de campo pueden referenciar.

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

Enlaces relacionados

• Uso de WPForms con asistentes de IA, la guía sin código para conectar un asistente de IA
• Presentación de la API de capacidades de WordPress (developer.wordpress.org)
• wordpress/mcp-adapter en GitHub
• Protocolo de contexto de modelo