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

WPForms 1.9.9 introdujo una API REST de solo lectura basada en la API de Habilidades de WordPress. Puedes listar formularios, obtener la configuración del formulario, recuperar y buscar entradas, y extraer estadísticas del formulario desde cualquier cliente HTTP, la línea de comandos, tu 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 de solo lectura bajo el espacio de nombres wpforms/. Cada habilidad ejecuta las mismas comprobaciones de capacidad 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 GET autenticada a /wp-json/wp-abilities/v1/abilities/<ability>/run. Dado que cada habilidad de WPForms es de solo lectura, solo se acepta GET; POST 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.

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.

Referencia de Habilidad

Todas las habilidades son de solo lectura e idempotentes. 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
}

Uso de WPForms con clientes MCP

Cada capacidad de WPForms se registra con mcp.public establecido en true, lo que significa 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. Después de la instalación, no se requiere ninguna configuración adicional del lado de WPForms; 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.

Enlaces relacionados

• Presentación de la API de capacidades de WordPress (developer.wordpress.org)
• wordpress/mcp-adapter en GitHub
• Protocolo de contexto de modelo