Fin du connecteur Net Reviews : migrer WooCommerce vers l’API Purchase Events d’Avis Vérifiés (Skeepers)

Si vous gérez une boutique WooCommerce et que vous utilisez Avis Vérifiés (Skeepers) pour collecter les avis de vos clients, vous avez probablement reçu un mail qui a de quoi inquiéter :

"Nous vous informons qu'à compter du 22 novembre, le connecteur WooCommerce que vous utilisez actuellement pour nous transmettre vos commandes ne sera plus maintenu. [...] Passé cette date, nous ne pourrons plus garantir le bon fonctionnement de ce connecteur ni intervenir en cas d'interruption."

En clair : le plugin Net Reviews, historiquement utilisé par de nombreuses boutiques WooCommerce pour transmettre automatiquement les commandes à Avis Vérifiés, arrive en fin de vie. Sans action de votre part, vos clients cesseront progressivement de recevoir des demandes d'avis après un achat (avis produits/marque).

Skeepers propose deux alternatives : un envoi par SFTP (fichiers déposés périodiquement), ou une intégration via leur nouvelle API Purchase Events. Dans cet article, je vous montre comment j'ai mis en place la seconde option qui est plus fiable, en temps réel, et qui ne dépend d'aucun plugin tiers non maintenu.

L'approche que je détaille ici a un avantage clé : pas de serveur intermédiaire à héberger. Tout se passe directement dans WordPress, via un petit plugin custom qui se branche sur les hooks WooCommerce natifs.

L’essentiel à savoir

• Le connecteur Net Reviews pour WooCommerce ne sera plus maintenu par Skeepers à partir du 22 novembre
• Skeepers propose deux alternatives : SFTP ou API Purchase Events
• Solution présentée ici : un plugin WordPress custom (une centaine de lignes de PHP), sans service tiers à héberger
• Le plugin s'authentifie via OAuth2 puis envoie chaque commande WooCommerce à l'API Skeepers au moment choisi (paiement confirmé, commande terminée, etc.)
• Deux pièges fréquents à connaître : le plafond de pression marketing et le catalogue produit recalculé chaque nuit

Pourquoi ne pas simplement utiliser un plugin existant ?

C'est la question que je me suis posée en premier. À l'heure où j'écris cet article, il n'existe pas encore de plugin WordPress officiel maintenu par Skeepers pour cette nouvelle API.

Plutôt que d'attendre ou de dépendre d'un service tiers externe (un serveur Node.js à héberger séparément, par exemple), j'ai opté pour la solution la plus directe : un plugin WordPress "maison" et simple d'une centaine de lignes, qui s'accroche directement aux événements WooCommerce.

Étape 1 : Récupérer vos identifiants API

Tout commence dans votre back-office Avis Vérifiés :

1. Connectez-vous sur https://app.netreviews.eu/
2. Rendez-vous dans Collecte des avis > Configuration
3. Onglet API
4. Cliquez sur Créer votre compte API pour générer un Client ID et un Client secret

Conservez précieusement ces deux valeurs.

Il faut également retrouver le website_id, un identifiant UUID propre à votre site. Pour cela, allez dans Gestion du compte > Mon Compte. Le website_id se trouvent alors à droite de la page dans le bloc nommé "Code d'intégration".

Étape 2 : Comprendre l’authentification de l’API

L'API Purchase Events utilise le protocole OAuth2 (client credentials). Avant de pouvoir envoyer une commande, il faut obtenir un token d'accès via une requête POST :

POST https://auth.skeepers.io/realms/skeepers/protocol/openid-connect/token
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=openid

La réponse contient un access_token valable une durée limitée (expires_in, généralement quelques minutes). Ce token doit ensuite être passé en en-tête Authorization: Bearer <token> sur l'appel suivant, celui qui envoie réellement la commande :

POST https://api.skeepers.io/purchase-event/websites/{website_id}/purchase_events/bulk_sync_insert

Avec quel outil tester cette requête ?

Avant même d'écrire la moindre ligne de PHP, je vous recommande de tester cette authentification en ligne de commande, pour vérifier que vos identifiants fonctionnent. L'outil à utiliser dépend de votre système d'exploitation :

Sur Mac (ou Linux)

curl est installé nativement. Ouvrez l'application Terminal et lancez directement :

curl -X POST "https://auth.skeepers.io/realms/skeepers/protocol/openid-connect/token" \
  -u "votre_client_id:votre_client_secret" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=openid"

Sur Windows

Deux options :

• PowerShell (pré-installé) : depuis Windows 10, la commande ci-dessus fonctionne donc telle quelle dans PowerShell.
• Git Bash (installé avec Git for Windows) : si vous l'avez déjà sur votre machine (courant chez les développeurs), il reproduit un environnement Bash identique à Mac/Linux, avec curl disponible nativement.

Alternative avec interface graphique (recommandée si vous n'êtes pas à l'aise avec le terminal)

Des outils comme Postman ou Insomnia (gratuits, disponibles sur Mac et Windows) permettent de construire et tester ces requêtes API via une interface visuelle, sans taper de ligne de commande. C'est souvent plus confortable pour une première prise en main : vous renseignez l'URL, les en-têtes et le corps de la requête dans des champs dédiés, puis cliquez sur "Send" pour voir la réponse.

Étape 3 : Choisir le bon déclencheur WooCommerce

C'est le point sur lequel je me suis le plus attardé, car le choix du hook WooCommerce change complètement le comportement de l'intégration. WooCommerce propose plusieurs événements possibles :

• woocommerce_checkout_order_processed — Se déclenche dès que le client valide sa commande, avant confirmation du paiement. Rapide, mais risque d'envoyer des commandes jamais payées.
• woocommerce_payment_complete — Se déclenche dès que le paiement est confirmé. Bon compromis : la commande est réellement payée, sans attendre un traitement manuel.
• woocommerce_order_status_completed — Se déclenche quand la commande est manuellement marquée "Terminée" (souvent à l'expédition). Fiable, mais peut être tardif si les commandes ne sont pas clôturées rapidement par votre équipe.

⚠️ Point important à noter : contrairement à ce qu'on pourrait penser, le simple fait d'avoir des articles dans le panier ou de consulter la page de paiement ne déclenche rien. Il faut que le client valide effectivement sa commande.

Pour ma part, j'ai commencé avec woocommerce_order_status_completed (le plus simple à tester), avant d'envisager de basculer sur woocommerce_payment_complete pour ne pas dépendre d'une clôture manuelle des commandes.

Étape 4 : Le plugin complet

Voici le plugin que j'utilise, sous forme d'un fichier unique à placer dans wp-content/plugins/. Il gère :

• La récupération et la mise en cache du token (pour éviter de le redemander à chaque commande)
• La construction du payload à partir de la commande WooCommerce
• L'envoi à l'API Skeepers
• Un marqueur anti-doublon (une commande n'est envoyée qu'une seule fois)
• Des logs pour faciliter le debug

<?php
/**
 * Plugin Name: Skeepers Purchase Events
 * Description: Envoie automatiquement chaque commande WooCommerce vers l'API Purchase Events de Skeepers.
 * Version: 1.0
 * Author: Thibaut Soufflet
 * Author URI: http://www.author.url
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

// À adapter avec vos identifiants (voir remarque sécurité plus bas)
define( 'SKEEPERS_CLIENT_ID', 'votre_client_id' );
define( 'SKEEPERS_CLIENT_SECRET', 'votre_client_secret' );
define( 'SKEEPERS_WEBSITE_ID', 'votre_website_id' );

define( 'SKEEPERS_AUTH_URL', 'https://auth.skeepers.io/realms/skeepers/protocol/openid-connect/token' );
define( 'SKEEPERS_API_URL', 'https://api.skeepers.io/purchase-event/websites/' . SKEEPERS_WEBSITE_ID . '/purchase_events/bulk_sync_insert' );

add_action( 'woocommerce_order_status_completed', 'skeepers_send_purchase_event', 10, 1 );

function skeepers_get_access_token() {
    $cached_token = get_transient( 'skeepers_access_token' );
    if ( $cached_token ) {
        return $cached_token;
    }

    $response = wp_remote_post( SKEEPERS_AUTH_URL, array(
        'headers' => array(
            'Authorization' => 'Basic ' . base64_encode( SKEEPERS_CLIENT_ID . ':' . SKEEPERS_CLIENT_SECRET ),
            'Content-Type'  => 'application/x-www-form-urlencoded',
        ),
        'body'    => array(
            'grant_type' => 'client_credentials',
            'scope'      => 'openid',
        ),
        'timeout' => 15,
    ) );

    if ( is_wp_error( $response ) ) {
        error_log( 'Skeepers - Erreur auth : ' . $response->get_error_message() );
        return false;
    }

    $body = json_decode( wp_remote_retrieve_body( $response ), true );

    if ( empty( $body['access_token'] ) ) {
        error_log( 'Skeepers - Réponse auth inattendue : ' . wp_remote_retrieve_body( $response ) );
        return false;
    }

    $expires_in = isset( $body['expires_in'] ) ? intval( $body['expires_in'] ) - 30 : 60;
    set_transient( 'skeepers_access_token', $body['access_token'], max( $expires_in, 30 ) );

    return $body['access_token'];
}

function skeepers_send_purchase_event( $order_id ) {
    $order = wc_get_order( $order_id );
    if ( ! $order ) {
        return;
    }

    if ( $order->get_meta( '_skeepers_event_sent' ) === 'yes' ) {
        return;
    }

    $products = array();
    foreach ( $order->get_items() as $item ) {
        $product = $item->get_product();
        $products[] = array(
            'product_ref' => array(
                'reference' => (string) $item->get_product_id(),
                'sku'       => $product ? $product->get_sku() : null,
            ),
            'name'  => $item->get_name(),
            'price' => (float) $item->get_total(),
        );
    }

    $payload = array(
        array(
            'purchase_reference' => (string) $order->get_order_number(),
            'purchase_date'      => $order->get_date_created() ? $order->get_date_created()->date( 'c' ) : gmdate( 'c' ),
            'price'              => (float) $order->get_total(),
            'consumer'           => array(
                'first_name' => $order->get_billing_first_name(),
                'last_name'  => $order->get_billing_last_name(),
                'email'      => $order->get_billing_email(),
                'phone'      => $order->get_billing_phone() ?: null,
                'country'    => $order->get_billing_country() ?: null,
                'language'   => 'fr',
            ),
            'products'      => $products,
            'sales_channel' => array(
                'channel'       => 'online',
                'delivery_type' => 'home_delivery',
                'website_id'    => SKEEPERS_WEBSITE_ID,
            ),
        ),
    );

    $token = skeepers_get_access_token();
    if ( ! $token ) {
        error_log( 'Skeepers - Impossible d\'envoyer la commande #' . $order_id . ' : pas de token.' );
        return;
    }

    $response = wp_remote_post( SKEEPERS_API_URL, array(
        'headers' => array(
            'Authorization' => 'Bearer ' . $token,
            'Content-Type'  => 'application/json',
        ),
        'body'    => wp_json_encode( $payload ),
        'timeout' => 15,
    ) );

    if ( is_wp_error( $response ) ) {
        error_log( 'Skeepers - Erreur envoi commande #' . $order_id . ' : ' . $response->get_error_message() );
        return;
    }

    $status_code = wp_remote_retrieve_response_code( $response );

    if ( $status_code === 201 ) {
        $order->update_meta_data( '_skeepers_event_sent', 'yes' );
        $order->save();
        error_log( 'Skeepers - Commande #' . $order_id . ' envoyée avec succès.' );
    } else {
        error_log( 'Skeepers - Réponse inattendue (' . $status_code . ') pour commande #' . $order_id . ' : ' . wp_remote_retrieve_body( $response ) );
    }
}

Pensez à mettre ce fichier dans un dossier .zip avant de le téléverser dans les Extensions comme un plugin classique. Nommez le dossier de façon explicite "skeeper-purchase-events" par exemple.

⚠️ Remarque sur la sécurité des identifiants

Dans l'exemple ci-dessus, les identifiants sont définis directement dans le fichier du plugin pour la simplicité de la démonstration. En production, je vous recommande plutôt de les définir dans votre wp-config.php (fichier généralement mieux protégé et hors du dossier plugins) :

define( 'SKEEPERS_CLIENT_ID', 'votre_client_id' );
define( 'SKEEPERS_CLIENT_SECRET', 'votre_client_secret' );
define( 'SKEEPERS_WEBSITE_ID', 'votre_website_id' );

Et de retirer ces lignes du plugin lui-même car WordPress les rendra de fait disponibles globalement.

Étape 5 : Tester et déboguer

Avant de considérer l'intégration comme opérationnelle, activez les logs WordPress dans wp-config.php :

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Passez ensuite une commande de test, marquez-la comme "Terminée" (ou déclenchez le hook que vous avez choisi), puis surveillez wp-content/debug.log.

Pour ce faire, passez par FTP (FileZilla par exemple) et ouvrez le fichier situé wp-content/debug.log

Un envoi réussi renvoie un statut HTTP 201 avec le détail de l'événement créé côté Skeepers.

Dans votre back-office Avis Vérifiés, vous devriez voir également votre commande de test s'afficher dans Collecte des avis > Suivi des demandes d'avis

Deux pièges à connaître absolument

Pendant mes tests, je suis tombé sur deux comportements qui peuvent surprendre et faire croire à un bug alors que tout fonctionne :

1. Le plafond de "pression marketing"

Si vous testez plusieurs fois avec la même adresse e-mail, Skeepers peut retourner un statut 206 avec l'erreur "error_description": "Purchase blocked by pressure marketing" (visible dans les log du fichier debug.log). C'est normal : c'est une protection anti-spam qui limite la fréquence des sollicitations d'avis envoyées à un même client. Ce n'est pas une erreur d'intégration, testez avec une adresse e-mail différente pour vérifier que le flux fonctionne bien de bout en bout.

2. Le catalogue produit se met à jour la nuit

Si l'avis "Marque" se déclenche mais pas l'avis "Produit", ne cherchez pas de bug dans votre code. Le catalogue produit de Skeepers est reconstruit chaque nuit à partir des commandes reçues : un produit acheté pour la première fois aujourd'hui n'apparaîtra dans le catalogue que le lendemain, et ce n'est qu'à partir de ce moment que les sollicitations d'avis produit pourront se déclencher pour ce produit.

Et au sujet de l’échéance ?

Le 22 novembre, c'est dans peu de temps, et la migration touche potentiellement des milliers de boutiques WooCommerce qui utilisaient encore le connecteur Net Reviews. Si vous n'êtes pas à l'aise avec le code ou si vous manquez de temps, je peux m'occuper de cette migration pour vous, de la configuration de vos identifiants API jusqu'aux tests en conditions réelles.

N'attendez pas la dernière minute : passé le 22 novembre, Skeepers ne garantit plus le bon fonctionnement du connecteur actuel, ce qui veut dire une interruption possible de la collecte d'avis, sans certitude de pouvoir intervenir dans l'urgence.