La Abilities API de WordPress da a cada plugin una forma única de describir lo que sabe hacer, para que otro código pueda encontrarlo y llamarlo sin aprender la API propia de cada plugin. Vireo registra sus informes como habilidades (abilities). Tu plugin, un tema, un script de WP-CLI o una herramienta de IA pueden llamarlas y obtener las mismas cifras que el panel.
Necesitas WordPress 6.9 o posterior, donde la Abilities API forma parte del núcleo.
Qué hay
Las habilidades de Vireo están en la categoría vireo-analytics y se llaman vireo-analytics/get-.... El plugin gratuito registra 23; Vireo Pro añade las suyas, entre ellas get-revenue-forecast y get-subscriptions para tiendas. Todas son de solo lectura. La referencia de la API las lista todas con sus entradas.
Lístalas desde PHP:
foreach ( wp_get_abilities() as $ability ) {
if ( 0 === strpos( $ability->get_name(), 'vireo-analytics/' ) ) {
echo $ability->get_name() . ': ' . $ability->get_label() . "\n";
}
}
O por REST, con una contraseña de aplicación:
curl -u "your-username:xxxx xxxx xxxx xxxx xxxx xxxx" \
"https://example.com/wp-json/wp-abilities/v1/abilities?category=vireo-analytics&per_page=50"
Cada entrada incluye el esquema de entrada de la habilidad, así que puedes ver qué acepta.
Ejecuta una desde PHP
$ability = wp_get_ability( 'vireo-analytics/get-top-pages' );
$result = $ability ? $ability->execute( array( 'limit' => 2 ) ) : null;
if ( is_wp_error( $result ) ) {
error_log( $result->get_error_message() );
} else {
foreach ( $result['rows'] as $page ) {
printf( "%d %s\n", $page['pageviews'], $page['title'] );
}
}
execute() devuelve los datos como un array de PHP, o un WP_Error. En JSON:
{"rows":[
{"post_id":4,"path":"/2026/10/11/how-to-pack-for-a-month/","title":"How to pack for a month","pageviews":6,"visitors":6},
{"post_id":6,"path":"/2026/10/11/pricing/","title":"Pricing","pageviews":3,"visitors":3}
]}
Qué devuelven
Todas las habilidades devuelven un objeto, nunca una lista suelta:
- Las que devuelven una lista la ponen bajo
rows: estadísticas diarias, estadísticas por hora, páginas principales, referentes principales, fuentes de tráfico, países, eventos, vitals, notas del gráfico y objetivos. Si no hay nada que informar, es{"rows": []}. - Las demás devuelven su propio objeto, como
get-totalsconpageviews,visitors,days,avg_dailyy, desde la 0.13.0,avg_time_on_page_seconds,timed_viewsybounce_rate_percent.
La forma es la misma tanto si llamas a la habilidad desde PHP, por REST o a través de MCP. La referencia de la API lista lo que devuelve cada una.
Ejecuta una por REST
Las habilidades de solo lectura se ejecutan con GET en /wp-json/wp-abilities/v1/abilities/{name}/run. El nombre conserva su barra. Pasa las entradas como parámetros de consulta con la forma input[...]:
curl -g -u "your-username:xxxx xxxx xxxx xxxx xxxx xxxx" \
"https://example.com/wp-json/wp-abilities/v1/abilities/vireo-analytics/get-totals/run?input[start]=2026-09-12&input[end]=2026-10-11"
{"pageviews":15,"visitors":15,"days":30,"avg_daily":1,"avg_time_on_page_seconds":null,"timed_views":0,"bounce_rate_percent":null}
El -g de curl evita que interprete los corchetes como un patrón.
Sin ninguna entrada, la habilidad usa sus valores por defecto:
curl -u "your-username:xxxx xxxx xxxx xxxx xxxx xxxx" \
"https://example.com/wp-json/wp-abilities/v1/abilities/vireo-analytics/get-traffic-sources/run"
Lo que devuelve un error:
POSTdevuelve 405, «Read-only abilities require GET method».?input={"limit":1}como una sola cadena JSON devuelve 400, «input is not of type object». Usainput[limit]=1.- Una entrada que la habilidad no declara devuelve 400, por ejemplo «foo is not a valid property of Object».
Entradas y valores por defecto
startyend, comoYYYY-MM-DD, usan por defecto los últimos 30 días en la zona horaria de tu sitio. A diferencia de las rutas REST/stats/, son opcionales.limitva de 1 a 100. Cada habilidad tiene su propio valor por defecto.- Algunas habilidades necesitan una entrada más, como
post_idenget-post-statsohostenget-referrer-detail. La referencia indica cuáles. - Todo lo demás se rechaza. Una clave de entrada no declarada hace que
execute()devuelva unWP_Errorcon el códigoability_invalid_input, en lugar de ignorarse.
Permisos
Una habilidad se ejecuta como el usuario actual, y Vireo comprueba la misma capacidad (capability) que el panel, view_vireo_analytics. En PHP, es quien tenga la sesión iniciada en esa petición. En un cron o con WP-CLI no hay usuario a menos que establezcas uno:
wp_set_current_user( $user_id_with_dashboard_access );
Sin la capacidad, execute() devuelve un WP_Error con el código ability_invalid_permissions, y REST responde 401 o 403.
Las habilidades de Pro también necesitan una licencia de Vireo Pro activa, y las de tienda necesitan que esté activa una tienda compatible: WooCommerce, Easy Digital Downloads, FluentCart, Freemius, Paid Memberships Pro, Restrict Content, MemberPress, LifterLMS, GiveWP o SureCart. Si no se cumple eso, las habilidades no se registran, y wp_get_ability() devuelve null. get-goals la registra el plugin gratuito en todos los casos y responde cuando Pro está activo.
Para restringir más el acceso, por ejemplo a una lista de usuarios, usa el filtro vireo_abilities_permission_callback. Puede rechazar una llamada; no puede concedérsela a un usuario sin la capacidad.
Cadenas que vienen de los visitantes
Las rutas, los términos de búsqueda, los referentes y los valores de eventos los puede fijar cualquiera que envíe una petición a tu sitio. Antes de que una habilidad los devuelva, Vireo elimina los caracteres de control, los saltos de línea y los corchetes, y recorta los valores largos. Es seguro mostrárselos a un modelo de IA como datos, pero trátalos como texto no fiable en tu propio HTML: escápalos como harías con cualquier entrada de usuario.