# WordPress 6.9 et les Abilities API appliquées à un flux de commande WooCommerce

> Exposer une action de commande WooCommerce à un agent externe devient possible nativement avec WordPress 6.9. Ce que déclarer une capacité implique vraiment.

- Auteur : Clément Hadrot
- Publié le : 2026-06-04
- Mis à jour le : 2026-06-04
- Catégorie : E-commerce
- URL : https://wpmoderne.dev.wordpress-developpement.fr/ecommerce/wordpress-69-abilities-api-flux-commande-woocommerce/

## L’essentiel

- Une capacité déclarée expose une action précise, jamais un accès libre à la base
- Les garde-fous se posent au niveau de la capacité, pas au niveau de l'agent
- Toute action d'écriture doit rester réversible ou tracée

« Ability : a discrete, well-defined unit of functionality that can be discovered, described, and invoked programmatically. » La définition donnée par le projet WordPress pour les Abilities API tient en une phrase, mais elle change la façon dont un développeur doit penser l'exposition d'une action WooCommerce à un système externe.

Jusqu'à WordPress 6.9, sorti en décembre 2025, exposer une action de commande à un agent conversationnel ou à un outil d'automatisation passait par un point de terminaison REST personnalisé, construit et sécurisé à la main. Les Abilities API standardisent cette exposition directement dans le cœur, avec une déclaration explicite de ce qu'une capacité fait, de ses paramètres attendus et de son résultat.

## Ce qu'une capacité déclare exactement

Une capacité (*ability*) se déclare via la fonction `wp_register_ability()`, en fournissant un identifiant unique, une description en langage naturel destinée à un agent, un schéma d'entrée, un schéma de sortie et une fonction de rappel d'exécution. Rien de cela ne remplace les vérifications de capacité WordPress classiques : `current_user_can()` reste appelé à l'intérieur du callback, exactement comme pour un point de terminaison REST standard.

```
wp_register_ability( 'woocommerce/marquer-commande-expediee', array(
    'label'               => 'Marquer une commande comme expédiée',
    'description'         => 'Change le statut d\'une commande WooCommerce en "completed" et enregistre le numéro de suivi.',
    'input_schema'        => array(
        'type'       => 'object',
        'properties' => array(
            'order_id'        => array( 'type' => 'integer' ),
            'tracking_number' => array( 'type' => 'string' ),
        ),
        'required'   => array( 'order_id' ),
    ),
    'execute_callback'    => 'wpm_executer_expedition_commande',
    'permission_callback' => function() {
        return current_user_can( 'edit_shop_orders' );
    },
) );
```

## Pourquoi ce n'est pas juste un endpoint REST de plus

> L'essentiel à retenir : Une capacité déclarée expose une action précise, jamais un accès libre à la base ; Les garde-fous se posent au niveau de la capacité, pas au niveau de l'agent ; Toute action d'écriture doit rester réversible ou tracée

La différence tient à la découvrabilité. Un point de terminaison REST classique doit être documenté à part pour qu'un agent externe sache qu'il existe et comment l'appeler. Une capacité déclarée via les Abilities API est listée par un registre interrogeable, avec sa description en langage naturel directement lisible par un agent : c'est ce registre que consomme un serveur MCP construit sur WordPress, sans duplication de documentation entre le code et le prompt fourni à l'agent.

Pour un flux de commande WooCommerce, cela change concrètement l'organisation du code : au lieu d'un contrôleur REST dédié par action métier, on déclare une capacité par action significative, avec un schéma d'entrée strict qui sert à la fois de validation et de documentation vivante.

## Les garde-fous à poser avant toute exposition

Déclarer une capacité qui modifie une commande WooCommerce impose des vérifications supplémentaires à celles d'un simple appel REST authentifié, car l'appelant n'est plus nécessairement un humain qui relit ce qu'il envoie :

- Restreindre strictement les transitions de statut autorisées dans le callback, jamais un statut arbitraire passé en paramètre libre.
- Journaliser chaque invocation de capacité d'écriture avec l'identité de l'appelant, via une note de commande WooCommerce classique (`$order->add_order_note()`).
- Limiter le montant ou la portée d'une action financière (remboursement, annulation) par une valeur seuil codée en dur, non modifiable par le paramètre d'entrée.
- Prévoir un mode de simulation (*dry-run*) pour les capacités les plus sensibles, activable en paramètre optionnel du schéma d'entrée.

## Nouveautés classées par impact sur un flux de commande

### Impact fort

Le registre central des capacités (`wp_get_ability()`, listing global) permet à un serveur MCP externe de découvrir automatiquement les actions de commande disponibles sans configuration manuelle côté agent, ce qui réduit fortement le code de câblage nécessaire par rapport à une exposition REST artisanale.

### Impact modéré

La validation par schéma JSON intégrée au cœur évite d'écrire à la main la validation des paramètres d'entrée pour chaque capacité, ce qui réduit les erreurs de type sur des champs comme l'identifiant de commande ou le montant.

### Impact faible mais réel

La déclaration de capacités cohabite avec les rôles et capacités WordPress existants (`edit_shop_orders`, etc.) sans nouveau système de permission parallèle, ce qui limite la dette de sécurité à long terme mais demande une relecture des rôles existants avant toute exposition.

## En résumé

Les Abilities API de WordPress 6.9 ne remplacent pas la prudence nécessaire à l'exposition d'actions de commande, elles la rendent explicite et vérifiable dans un registre unique. Pour un flux WooCommerce, l'enjeu reste le même qu'avant : chaque action d'écriture doit rester bornée, journalisée et réversible, avec ou sans agent externe à l'autre bout de l'appel.