Menú de la documentaciónUsa las habilidades de Vireo desde tu propio código

Usa las habilidades de Vireo desde tu propio código

Lista las habilidades (abilities) de Vireo, ejecútalas desde PHP con wp_get_ability() o por REST con la Abilities API, y gestiona permisos y errores.

En esta página

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-totals con pageviews, visitors, days, avg_daily y, desde la 0.13.0, avg_time_on_page_seconds, timed_views y bounce_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:

  • POST devuelve 405, «Read-only abilities require GET method».
  • ?input={"limit":1} como una sola cadena JSON devuelve 400, «input is not of type object». Usa input[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

  • start y end, como YYYY-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.
  • limit va de 1 a 100. Cada habilidad tiene su propio valor por defecto.
  • Algunas habilidades necesitan una entrada más, como post_id en get-post-stats o host en get-referrer-detail. La referencia indica cuáles.
  • Todo lo demás se rechaza. Una clave de entrada no declarada hace que execute() devuelva un WP_Error con el código ability_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.