Referencia de la API REST de WPForms y la API de Abilities

La versión 1.9.9 de WPForms introdujo una API REST de solo lectura basada en la API Abilities de WordPress. Puedes listar formularios, obtener la configuración de los formularios, recuperar y buscar entradas, así como consultar estadísticas de los formularios desde cualquier cliente HTTP, la línea de comandos, tu propio código PHP o asistentes de IA que utilicen el Protocolo de Contexto de Modelos (MCP).

Si has buscado «WPForms REST API» y has llegado hasta aquí, esto es lo que buscabas. No existe una API REST independiente; la integración con la API de Abilities es la forma en que WPForms expone sus datos a través de HTTP.

¿Qué es la API de Abilities?

La API de capacidades es una función integrada en el núcleo de WordPress que se incorporó en la versión 6.9. Permite a los plugins declarar capacidades individuales (denominadas habilidades) con un nombre, un esquema de entrada, un esquema de salida y una función de devolución de llamada de permisos. A continuación, WordPress expone automáticamente todas las capacidades registradas a través de la API REST en /wp-json/wp-abilities/v1/abilities/<ability>/run y a los clientes de IA compatibles con MCP a través del complemento adaptador oficial de MCP.

WPForms registra un conjunto de capacidades de solo lectura bajo el wpforms/ espacio de nombres. Cada función realiza las mismas comprobaciones de permisos de WPForms que se utilizan en el panel de administración (wpforms_current_user_can()), por lo que las interfaces REST y MCP heredan el modelo de permisos existente en lugar de introducir uno nuevo.

Activar una habilidad

Cada función se puede invocar mediante dos métodos. El resultado es el mismo; elige el que mejor se adapte al entorno de llamada.

API REST

Enviar un mensaje autenticado GET solicitar /wp-json/wp-abilities/v1/abilities/<ability>/run. Dado que todas las funciones de WPForms son de solo lectura, solo GET se acepta; POST devoluciones 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 del wp_abilities_api_init Si se ha activado la acción, recupera la habilidad con wp_get_ability() y llamarlo execute() método. Pasa los datos de entrada como una matriz asociativa de parámetros (con los mismos nombres que figuran 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 protocolo 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 complemento adicional.

Creación de una contraseña de aplicación

1. Inicia sesión como el usuario de WordPress con cuyos permisos deben ejecutarse las llamadas.
2. Ve a Usuarios » Perfil y desplázate hasta la sección «Contraseñas de aplicaciones ».
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 obtener más información, incluidos los puntos finales REST para gestionar las contraseñas de aplicación mediante programación, consulta la Guía de integración de contraseñas de aplicación del equipo del núcleo de WordPress.

Envío de las credenciales

Envía el nombre de usuario y la contraseña de la aplicación mediante la autenticación HTTP básica en cada solicitud.

Con curl

Configura la URL de tu sitio como variable de entorno para que los ejemplos de este documento se puedan ejecutar tal cual:

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

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

Con Postman, Insomnia u otros clientes

Configura el tipo de autenticación de la solicitud como «Autenticación básica» e introduce tu nombre de usuario y la contraseña de la aplicación. El cliente se encarga de la codificación por ti.

Configuración manual del encabezado

Envía tus credenciales codificadas en base64 Authorization encabezado:

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

En los ejemplos de solicitud que aparecen a continuación en este documento se omite el indicador de autenticación para facilitar la lectura. Añade el -u bandera (o el Authorization (encabezado) en cada solicitud real; de lo contrario, la API devuelve 401 Unauthorized.

Permisos

Cada función comprueba una función específica de WPForms antes de ejecutarse. Si la comprobación falla, devuelve un WP_Error con el estado HTTP 403.

Referencia de habilidades

Todas las funciones son de solo lectura e idempotentes. Los errores se devuelven como WP_Error objetos serializados a JSON con code, messagey data.status campos.

wpforms/lista-de-formularios

Lista de formularios con metadatos resumidos. Disponible en las versiones Lite y Pro.

Parámetros

Ejemplo de solicitud

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

Ejemplo de respuesta

{
  "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 un único formulario, incluyendo un subconjunto seleccionado de sus ajustes y, opcionalmente, la configuración de sus campos. Disponible en las versiones Lite y Pro.

Parámetros

Ejemplo de solicitud

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

Ejemplo de respuesta

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

En settings El objeto devuelto por esta función es un subconjunto seleccionado y no confidencial (título, descripción, texto de envío, indicador de envío AJAX, honeypot, antispam). Los ajustes de notificación, confirmación e integración no se muestran.

wpforms/obtener-estadísticas-del-formulario

Estadísticas de envío de un formulario. La estructura de la respuesta varía entre las versiones Lite y Pro.

Parámetros

Ejemplo de solicitud

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

Respuesta simplificada

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

Respuesta profesional

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

wpforms/obtener-resúmenes-de-entradas

Lista paginada de resúmenes de entradas para un único formulario. Solo en la versión Pro.

Parámetros

Ejemplo de solicitud

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"

Ejemplo de respuesta

{
  "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 sola entrada por su ID, incluyendo todos los valores de los campos. Solo en la versión Pro.

Parámetros

Ejemplo de solicitud

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

Ejemplo de respuesta

{
  "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 de la respuesta puede ocultarse. Añadir add_filter( 'wpforms_abilities_mask_ip_address', '__return_true' ) en el código de tu sitio web; cuando está activada, las direcciones IPv4 aparecen con los tres últimos octetos sustituidos por asteriscos (por ejemplo, ***.***.***.100).

wpforms/búsqueda-de-entradas

Busca entradas en un solo formulario o en todos los formularios utilizando filtros de texto completo, específicos de campo, de estado y de intervalo de fechas. Solo en la versión Pro.

Parámetros

Ejemplo de solicitud

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"

Ejemplo de respuesta

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

Uso de WPForms con los clientes de MCP

Todas las funciones de WPForms están registradas en mcp.public configurar en true, lo que significa que los clientes de IA compatibles con MCP (Claude Desktop, Cursor y otros) los detectan automáticamente una vez que el sitio de WordPress se conecta a través del wordpress/adaptador-mcp complemento. Una vez instalado, no es necesario realizar ninguna configuración adicional en WPForms; las funciones aparecen en la lista de herramientas del cliente, en la sección WPForms categoría y respeten las mismas funciones de devolución de permisos que utiliza la API REST.

Descubrir capacidades mediante la programación

Para enumerar las funciones disponibles en un sitio web en lugar de introducir sus ID de forma estática:

# Mostrar todas las capacidades registradas en el sitio
curl "$WP_SITE/wp-json/wp-abilities/v1/abilities"

# Obtener el esquema de una capacidad concreta
curl "$WP_SITE/wp-json/wp-abilities/v1/abilities/wpforms/list-forms"

La respuesta incluye el ID, la etiqueta, la descripción y la categoría de cada función, así como los esquemas completos de entrada y salida, lo cual constituye información suficiente para crear un cliente genérico sin necesidad de conocer previamente la interfaz específica de WPForms.

Enlaces relacionados

• Presentamos la API de capacidades de WordPress (developer.wordpress.org)
• wordpress/mcp-adapter en GitHub
• Protocolo de contexto de modelos