Documentation de l'API

1. Introduction

La plateforme expose trois canaux distincts. Ils ne partagent ni le même public, ni le même régime d'authentification, ni les mêmes limites. Choisir le bon est la première décision d'une intégration.

Adresses de base

Toutes les URL de cette page sont relatives à l'adresse de l'API. Un module ne doit connaître qu'elle : les autres adresses lui sont renvoyées par GET /api/v1/cms/me, ce qui lui évite de les deviner et permet de les changer sans mettre à jour quoi que ce soit chez les marchands.

Conventions

• Format — JSON en entrée comme en sortie, encodé en UTF-8. L'en-tête Content-Type: application/json est attendu sur toute requête portant un corps.
• Nommage — serpent minuscule (external_order_id, experienced_at), la convention dominante des API que consomment les intégrateurs PHP et JavaScript.
• Dates — ISO 8601 avec fuseau explicite en entrée (2026-08-01T14:22:00+02:00). En sortie, les dates complètes sont au même format ; les dates publiques d'un avis sont réduites au jour (2026-08-01) parce qu'aucun widget n'affiche l'heure.
• Montants — transmis en chaîne ("129.90") et non en nombre flottant : un centime perdu à l'arrondi sur une commande devient un écart de facturation.
• Identifiants — les objets que nous créons portent un UUID permanent. Les vôtres (commande, produit, déclinaison) restent les vôtres : nous ne les réécrivons jamais.
• Erreurs — toujours la même enveloppe { "error": { "code": …, "message": … } }. Le code est stable et destiné à votre programme, le message à l'humain qui débogue. Voir §10.
• Versionnage — le /v1 du chemin est un contrat. Un champ optionnel peut y être ajouté à tout moment ; aucun champ existant ne sera renommé, supprimé ni rendu obligatoire. Une rupture partirait en /v2, l'ancienne version restant servie — les modules tournent chez les marchands et personne ne peut les mettre à jour à distance. Votre code doit donc ignorer les champs qu'il ne connaît pas plutôt qu'échouer à leur vue.

Obtenir une clé d'API

1. Créez un compte marchand sur l'espace marchand.
2. Confirmez l'adresse email, puis ouvrez la section des clés d'API.
3. Notez le secret : il n'est affiché qu'une fois. Perdu, il ne se retrouve pas — une nouvelle clé se crée, l'ancienne se révoque.

Un module d'installation n'a pas besoin de cette manipulation : il ouvre lui-même une demande de raccordement que le marchand valide d'un clic. Voir §3.

2. Authentification

L'API CMS et le serveur MCP utilisent le même mécanisme : une clé qui dit qui appelle, et une signature qui prouve que l'appelant détient le secret. Ce sont deux choses distinctes.

2.1 La signature, pas à pas

Étape 1 — Les trois en-têtes

Étape 2 — Construire la charge à signer

Quatre morceaux concaténés sans séparateur, dans cet ordre exact :

charge = X-Timestamp
       + MÉTHODE HTTP en majuscules
       + chemin logique de la requête
       + corps brut de la requête

Étape 3 — Calculer

X-Signature = "sha256=" + HMAC_SHA256(charge, secret)   // hexadécimal minuscule

Étape 4 — Vérifier votre implémentation sur cet exemple

Ces valeurs sont figées et la signature affichée est réellement celle de ces données : si votre code produit autre chose, le problème est dans votre code, pas dans le nôtre.

secret       : sk_demo_3f9c1a7e5b2d48a6
X-Timestamp  : 1786000000
méthode      : POST
chemin       : /api/v1/cms/reviews/9f1c2b3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d/response
corps        : {"content":"Merci pour votre retour !"}

Charge à signer (une seule ligne, aucun espace ajouté) :

1786000000POST/api/v1/cms/reviews/9f1c2b3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d/response{"content":"Merci pour votre retour !"}

Résultat attendu :

X-Signature: sha256=8a9c0de10516226f965465704902e00c666892b483b45b361f4536a6b2ee36e9

Le même calcul en une ligne de shell :

printf '%s' '1786000000POST/api/v1/cms/reviews/9f1c2b3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d/response{"content":"Merci pour votre retour !"}' \
  | openssl dgst -sha256 -hmac 'sk_demo_3f9c1a7e5b2d48a6' -r

printf et non echo : ce dernier ajoute un saut de ligne final, qui change la signature.

Étape 5 — Un appel complet en curl

SECRET='sk_demo_3f9c1a7e5b2d48a6'
CLE='ak_demo_5c2f81b0'
TS=$(date +%s)
CHEMIN='/api/v1/cms/orders'
CORPS='{"external_order_id":"CMD-1042","experienced_at":"2026-08-01T14:22:00+02:00","customer":{"email":"claire.martin@exemple.fr","first_name":"Claire","country":"FR","locale":"fr"},"source":{"platform":"custom","plugin_version":"1.0.0"}}'

SIG=$(printf '%s' "$TS""POST""$CHEMIN""$CORPS" \
      | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)

curl -X POST 'https://louis.guide/api/v1/cms/orders' \
  -H "X-Api-Key: $CLE" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: sha256=$SIG" \
  -H 'Content-Type: application/json' \
  --data-raw "$CORPS"

--data-raw et non --data : le second interprète certains caractères et peut modifier le corps envoyé, donc invalider la signature.

2.2 Exemple en PHP

Le client minimal, sans dépendance. C'est la même mécanique que celle des modules PrestaShop et WooCommerce, réduite à l'essentiel.

<?php

final class ClientGuideLouis
{
    public function __construct(
        private string $baseUrl,   // ex. 'https://louis.guide'
        private string $apiKey,
        private string $secret,
    ) {
    }

    /**
     * @param array<string, mixed> $donnees
     *
     * @return array{status: int, body: array<string, mixed>}
     */
    public function post(string $chemin, array $donnees): array
    {
        // ON SÉRIALISE UNE SEULE FOIS. La chaîne signée et la chaîne envoyée
        // doivent être le même objet : réencoder juste avant l'envoi produit
        // tôt ou tard une différence d'échappement, donc un 401 inexplicable.
        $corps = json_encode($donnees, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

        $timestamp = (string) time();

        // Le chemin LOGIQUE, sans l'adresse de base : c'est lui qui est signé.
        $chemin = '/' . ltrim($chemin, '/');

        $signature = hash_hmac(
            'sha256',
            $timestamp . 'POST' . $chemin . $corps,
            $this->secret,
        );

        $ch = curl_init(rtrim($this->baseUrl, '/') . $chemin);
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => $corps,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 10,
            CURLOPT_HTTPHEADER => [
                'Content-Type: application/json',
                'Accept: application/json',
                'X-Api-Key: ' . $this->apiKey,
                'X-Timestamp: ' . $timestamp,
                'X-Signature: sha256=' . $signature,
            ],
        ]);

        $reponse = (string) curl_exec($ch);
        $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        return ['status' => $status, 'body' => json_decode($reponse, true) ?: []];
    }
}

2.3 Les quatre pièges

Quatre causes expliquent la quasi-totalité des signature_mismatch. Elles se ressemblent toutes vues de l'extérieur — d'où l'intérêt de les écarter dans cet ordre.

1. Le corps a été réencodé après la signature. Le cas le plus fréquent, et le plus difficile à voir : un tableau sérialisé deux fois donne deux chaînes différentes dès qu'il contient un accent ou une barre oblique (JSON_UNESCAPED_UNICODE, JSON_UNESCAPED_SLASHES, ordre des clés). Signez la chaîne, envoyez cette chaîne, ne la reconstruisez jamais.
2. Le chemin signé porte un préfixe qu'il ne devrait pas avoir. Le chemin signé est /api/v1/cms/orders, même si l'API est servie depuis https://exemple.fr/plateforme/api/v1/cms/orders. Le préfixe d'installation appartient à l'adresse de base. À l'inverse, ne signez pas non plus l'URL complète avec son schéma et son hôte.
3. L'horloge du serveur dérive. Tolérance : 300 secondes d'écart, dans un sens comme dans l'autre. Au-delà, la réponse est timestamp_out_of_range et son message indique l'écart mesuré en secondes — l'information exacte à donner à votre hébergeur. Ce cas se manifeste souvent par une intégration qui « fonctionnait hier ».
4. La méthode ou le préfixe manquent. La méthode entre dans la charge en majuscules, et la valeur de X-Signature commence par sha256=. Un HMAC nu, sans préfixe, est rejeté.

Rejeu et fenêtre de validité

La charge signée couvre l'horodatage, la méthode, le chemin et le corps. Omettre l'un d'eux ouvrirait une faille : sans le chemin, une signature valide pour POST /orders serait rejouable sur DELETE /orders ; sans l'horodatage, la requête serait rejouable indéfiniment.

La fenêtre de 300 secondes est ce qui borne le rejeu : une requête interceptée ne peut être réémise au-delà. Il n'y a pas de dictionnaire de signatures déjà vues — à l'intérieur de cette fenêtre, une requête identique est donc acceptée deux fois. C'est sans effet sur la transmission des commandes, qui est idempotente par external_order_id : la seconde reçoit la commande déjà enregistrée et n'envoie pas un second email.

Réponses d'authentification

Toutes ces réponses portent le statut 401.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "code": "timestamp_out_of_range",
    "message": "Horodatage hors tolérance : +412 s d'écart avec notre serveur (maximum 300 s). L'horloge de votre serveur est probablement désynchronisée."
  }
}

3. Raccordement d'une boutique

Ces deux endpoints permettent à un module de récupérer une clé sans que le marchand ait à recopier quoi que ce soit. Le module ouvre une demande, affiche un lien, le marchand valide dans son navigateur, et le module reçoit sa clé et son secret à la lecture suivante.

Ils sont sans authentification, par construction. La sécurité ne repose pas sur une identité mais sur trois choses : la demande n'obtient rien tant qu'un marchand connecté ne l'a pas validée, le jeton de sondage ne quitte jamais le serveur de la boutique, et le secret n'est remis qu'une seule fois. Le pire qu'un appel malveillant puisse produire, c'est une demande en attente que personne n'approuvera — et qui expire en quinze minutes.

curl -X POST 'https://louis.guide/api/v1/pairing' \
  -H 'Content-Type: application/json' \
  --data-raw '{"shop_domain":"boutique.exemple.fr","platform":"prestashop","shop_name":"Tissu Fiesta","platform_version":"8.1.6","plugin_version":"1.2.0","shop_uid":"ps-7f3a91c4"}'

HTTP/1.1 201 Created

{
  "code": "4K7M-9QR3",
  "poll_token": "pt_8f2c1a7e5b2d48a6c3d9e0f1a2b3c4d5",
  "expires_at": "2026-08-13T15:07:44+00:00",
  "approve_url": "https://louis.guide/app/raccordement/4K7M-9QR3"
}

curl -X POST 'https://louis.guide/api/v1/pairing/4K7M-9QR3' \
  -H 'Content-Type: application/json' \
  --data-raw '{"poll_token":"pt_8f2c1a7e5b2d48a6c3d9e0f1a2b3c4d5"}'

HTTP/1.1 200 OK

{ "status": "pending" }

HTTP/1.1 200 OK

{
  "status": "approved",
  "api_key": "ak_live_5c2f81b0",
  "secret": "sk_live_3f9c1a7e5b2d48a6",
  "merchant": "tissufiesta"
}

4. API CMS (signée)

Le canal des intégrations serveur : modules e-commerce, ERP, CRM, outils internes. Toutes les URL sont préfixées par https://louis.guide.

Lectures : la clé suffit. Écritures : clé + signature. Le détail du calcul est au §2. Les fiches ci-dessous rappellent le régime de chacune par une pastille.

curl 'https://louis.guide/api/v1/cms/ping' \
  -H 'X-Api-Key: ak_live_5c2f81b0'

HTTP/1.1 200 OK

{
  "status": "ok",
  "merchant": "tissufiesta",
  "api_key": "ak_live_5c2f81b0",
  "server_time": "2026-08-13T14:52:07+00:00"
}

curl 'https://louis.guide/api/v1/cms/me' \
  -H 'X-Api-Key: ak_live_5c2f81b0'

HTTP/1.1 200 OK

{
  "merchant": {
    "uuid": "0f1c2b3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
    "slug": "tissufiesta",
    "display_name": "Tissu Fiesta",
    "country": "FR",
    "default_locale": "fr",
    "timezone": "Europe/Paris",
    "status": "active"
  },
  "plan": {
    "code": "pro",
    "can_display_product_reviews": true,
    "can_use_photos": true,
    "can_use_reviews_api": true,
    "can_remove_branding": true
  },
  "quota": {
    "year": 2026,
    "allowance": 5000,
    "used": 1284,
    "remaining": 3716,
    "resets_at": "2027-01-01T00:00:00+00:00"
  },
  "urls": {
    "api": "https://louis.guide",
    "dashboard": "https://louis.guide/app",
    "widget": "https://louis.guide/widget/v1/avis.js",
    "profile": "https://louis.guide/m/tissufiesta"
  },
  "server_time": "2026-08-13T14:52:07+00:00"
}

POST /api/v1/cms/orders
X-Api-Key: ak_live_5c2f81b0
X-Timestamp: 1786000000
X-Signature: sha256=…
Content-Type: application/json

{
  "external_order_id": "CMD-1042",
  "experienced_at": "2026-08-06T09:15:00+02:00",
  "amount": "129.90",
  "currency": "EUR",
  "order_status_id": "5",
  "order_status_label": "Livré",
  "customer": {
    "email": "claire.martin@exemple.fr",
    "first_name": "Claire",
    "last_name": "Martin",
    "locale": "fr",
    "country": "FR",
    "postal_code": "69003",
    "city": "Lyon"
  },
  "items": [
    {
      "external_product_id": "REF-42",
      "variant_id": "REF-42-ROUGE-L",
      "variant_label": "Couleur : rouge, Taille : L",
      "name": "Nappe en lin lavé",
      "sku": "NAP-LIN-42",
      "gtin": "3401579874120",
      "brand": "Tissu Fiesta",
      "quantity": 2,
      "unit_price": "64.95",
      "product_url": "https://boutique.exemple.fr/nappe-lin-42",
      "image_url": "https://boutique.exemple.fr/img/nappe-42.jpg"
    }
  ],
  "source": {
    "platform": "prestashop",
    "platform_version": "8.1.6",
    "plugin_version": "1.2.0",
    "trigger": "actionOrderHistoryAddAfter",
    "shop_uid": "ps-7f3a91c4",
    "shop_id": "1",
    "shop_name": "Tissu Fiesta"
  }
}

HTTP/1.1 201 Created

{
  "uuid": "3b8e1f42-6c7d-4e9a-91b2-5d0c3a7f4e18",
  "external_order_id": "CMD-1042",
  "status": "pending",
  "channel": "ecommerce_order",
  "experienced_at": "2026-08-06T07:15:00+00:00",
  "imported_at": "2026-08-06T09:41:22+00:00",
  "items_count": 1,
  "idempotent": false
}

HTTP/1.1 200 OK

{ "…": "…", "idempotent": true }

HTTP/1.1 422 Unprocessable Content

{
  "status": 422,
  "detail": "customer.email: \"claire.martin\" n'est pas une adresse email valide.",
  "violations": [
    {
      "propertyPath": "customer.email",
      "message": "\"claire.martin\" n'est pas une adresse email valide."
    }
  ]
}

curl 'https://louis.guide/api/v1/cms/reviews?status=published&per_page=50' \
  -H 'X-Api-Key: ak_live_5c2f81b0'

HTTP/1.1 200 OK

{
  "reviews": [
    {
      "id": "9f1c2b3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "score": 4,
      "title": "Livraison rapide",
      "comment": "Nappe conforme, le lin est épais. Un pli à la livraison.",
      "author": "Claire M.",
      "language": "fr",
      "country": "FR",
      "status": "published",
      "verified_purchase": true,
      "experienced_at": "2026-08-06T07:15:00+00:00",
      "submitted_at": "2026-08-13T18:02:41+00:00",
      "published_at": "2026-08-13T18:04:10+00:00",
      "order_reference": "CMD-1042",
      "response": {
        "content": "Merci Claire, nous notons pour l'emballage.",
        "created_at": "2026-08-14T08:11:00+00:00",
        "updated_at": null
      },
      "report": null
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 318
}

curl -X POST 'https://louis.guide/api/v1/cms/reviews/9f1c2b3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d/response' \
  -H 'X-Api-Key: ak_live_5c2f81b0' \
  -H 'X-Timestamp: 1786000000' \
  -H 'X-Signature: sha256=…' \
  -H 'Content-Type: application/json' \
  --data-raw '{"content":"Merci Claire, nous notons pour l’emballage."}'

HTTP/1.1 201 Created

{
  "review_id": "9f1c2b3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
  "response": {
    "content": "Merci Claire, nous notons pour l'emballage.",
    "created": true,
    "status": "published",
    "published": true
  }
}

HTTP/1.1 202 Accepted

{
  "review_id": "9f1c2b3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
  "report": {
    "reason": "off_topic",
    "status": "pending",
    "review_remains_visible": true
  }
}

5. API publique

Lecture seule, sans authentification, sur /api/v1/public/. C'est ce que consomment les widgets, et ce que peut consommer n'importe quel affichage sur mesure.

Le {slug} des chemins est l'identifiant public du marchand — celui de sa page publique, visible dans urls.profile renvoyé par /cms/me.

Ce qui protège une API sans clé

Il n'y a pas d'identité à vérifier : ce code s'exécute chez les visiteurs d'une boutique, aucun secret ne peut y vivre. La protection tient donc à trois autres choses, qu'il faut connaître avant d'intégrer.

• Aucune donnée sensible ne sort d'ici. Ni email, ni empreinte d'email, ni référence de commande, ni identifiant interne. Un widget affiche des avis publics ; tout ce qui sort par ce canal est lisible par n'importe qui.
• Débit limité à 60 requêtes par minute et par adresse IP, en fenêtre glissante. Une fiche produit fait deux appels (note + avis) : cela laisse 30 chargements par minute depuis une même adresse — large pour un visiteur, étroit pour un aspirateur de contenu. Voir §9.
• CORS restreint aux domaines déclarés du marchand. Un joker * autoriserait n'importe quel site — concurrent, comparateur, contrefacteur — à afficher les avis de n'importe quel marchand comme s'ils étaient les siens.

Cache

Toutes les réponses sont publiques et mises en cache : 60 secondes pour les avis et les notes, 300 secondes pour les réglages d'affichage. C'est ce qui permet d'absorber le trafic d'une boutique en promotion sans dimensionner pour le pic. Ne construisez pas un affichage qui suppose l'apparition instantanée d'un avis publié.

curl 'https://louis.guide/api/v1/public/merchants/tissufiesta/score'

HTTP/1.1 200 OK
Cache-Control: public, max-age=60

{
  "merchant": { "slug": "tissufiesta", "name": "Tissu Fiesta" },
  "score": {
    "average": 4.6,
    "count": 318,
    "distribution": { "1": 4, "2": 6, "3": 18, "4": 91, "5": 199 },
    "scale": { "min": 1, "max": 5 }
  }
}

HTTP/1.1 200 OK

{
  "reviews": [
    {
      "id": "9f1c2b3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "author": "Claire M.",
      "score": 4,
      "title": "Livraison rapide",
      "comment": "Nappe conforme, le lin est épais. Un pli à la livraison.",
      "language": "fr",
      "verified_purchase": true,
      "experienced_at": "2026-08-06",
      "submitted_at": "2026-08-13",
      "published_at": "2026-08-13",
      "disputed": false,
      "photos": [
        {
          "id": "6d2a1f80-9b3c-4d5e-8f70-1a2b3c4d5e6f",
          "url": "https://louis.guide/photos/6d2a1f80-9b3c-4d5e-8f70-1a2b3c4d5e6f",
          "thumbnail_url": "https://louis.guide/photos/6d2a1f80-9b3c-4d5e-8f70-1a2b3c4d5e6f/thumb",
          "width": 1600,
          "height": 1200
        }
      ],
      "reply": {
        "content": "Merci Claire, nous notons pour l'emballage.",
        "published_at": "2026-08-14"
      }
    }
  ],
  "page": 1,
  "per_page": 10
}

curl 'https://louis.guide/api/v1/public/products/tissufiesta/REF-42/score?with_variants=true'

HTTP/1.1 200 OK

{
  "product": { "external_id": "REF-42", "variant_id": null },
  "score": {
    "average": 4.4,
    "count": 27,
    "distribution": { "1": 0, "2": 1, "3": 3, "4": 7, "5": 16 },
    "scale": { "min": 1, "max": 5 }
  },
  "variants": [
    { "variant_id": "REF-42-ROUGE-L", "average": 4.8, "count": 12 },
    { "variant_id": "REF-42-BLEU-M", "average": 4.1, "count": 15 }
  ]
}

curl 'https://louis.guide/api/v1/public/products/tissufiesta/REF-42/reviews?variant=REF-42-ROUGE-L&per_page=5'

HTTP/1.1 200 OK

{
  "photos": [
    {
      "id": "6d2a1f80-9b3c-4d5e-8f70-1a2b3c4d5e6f",
      "url": "https://louis.guide/photos/6d2a1f80-9b3c-4d5e-8f70-1a2b3c4d5e6f",
      "thumbnail_url": "https://louis.guide/photos/6d2a1f80-9b3c-4d5e-8f70-1a2b3c4d5e6f/thumb",
      "width": 1600,
      "height": 1200
    }
  ]
}

HTTP/1.1 200 OK
Cache-Control: public, max-age=300

{
  "merchant": {
    "slug": "tissufiesta",
    "name": "Tissu Fiesta",
    "accent_color": "#7c3aed"
  },
  "display": {
    "badge_flottant": false,
    "badge_cote": "droite",
    "badge_decalage": 16,
    "seuil_avis": 1,
    "etoiles_fiche": true,
    "etoiles_vignettes": true,
    "onglet_avis": true,
    "bloc_accueil": true
  },
  "profile_url": "https://louis.guide/m/tissufiesta"
}

HTTP/1.1 200 OK

{ "status": "ok" }

6. Widgets d'affichage

Quatre éléments HTML à poser dans un thème. Un seul script à charger, aucune dépendance, aucune configuration : l'adresse de l'API est déduite de l'URL du script lui-même.

<script src="https://louis.guide/widget/v1/avis.js" async></script>

<avis-score marchand="tissufiesta"></avis-score>
<avis-liste marchand="tissufiesta" par-page="5"></avis-liste>

Le script est chargé une fois par page, où l'on veut ; les éléments peuvent être posés avant lui. Il est servi sous /widget/v1/ : une évolution incompatible partira en /v2/ et celui-ci restera servi tel quel — il vit dans des thèmes que personne ne mettra à jour.

Les quatre éléments

Attributs

Exemple complet sur une fiche produit

<!-- Sous le titre du produit -->
<avis-score marchand="tissufiesta" produit="REF-42" mini="3"></avis-score>

<!-- Photos des acheteurs, sous la galerie du catalogue -->
<avis-carrousel marchand="tissufiesta" produit="REF-42" max="8"></avis-carrousel>

<!-- Dans l'onglet « Avis » -->
<avis-liste marchand="tissufiesta" produit="REF-42" par-page="10"></avis-liste>

<!-- Une seule fois, dans le gabarit commun -->
<avis-flottant marchand="tissufiesta"></avis-flottant>

Ce que le marchand pilote sans vous

Les éléments lisent /display au chargement. Deux réglages leur viennent de là plutôt que d'un attribut, et c'est délibéré : le marchand peut poser ses balises une fois pour toutes, puis changer d'avis depuis son espace sans rouvrir son thème.

• La pastille flottante — allumée ou éteinte, à droite ou à gauche, avec son décalage. <avis-flottant> posé dans le gabarit n'affiche rien tant que le marchand ne l'a pas activée. Elle est éteinte par défaut : rien ne doit apparaître chez lui sans qu'il l'ait demandé.
• La couleur de marque — appliquée aux surfaces qui peuvent l'être. Les étoiles gardent leur ambre, le vert d'« Achat vérifié » et l'ambre de « Contesté » aussi : ces couleurs portent un sens, elles ne décorent pas, et les repeindre rendrait la note illisible chez un marchand dont la marque est jaune pâle ou blanche.

Les réglages ne sont demandés qu'une fois par page, même avec quatre éléments : la requête en vol est partagée. C'est ce qui évite au widget d'être le script qui ralentit la fiche produit — reproche fondé qu'on peut faire à la plupart des modules d'avis.

Isolation vis-à-vis du thème

Chaque élément rend son contenu dans un shadow DOM : le CSS du thème ne déborde pas sur le widget, et celui du widget ne déborde pas sur la boutique. Aucun des deux ne serait acceptable dans l'autre sens.

Corollaire à connaître avant d'essayer : vos règles CSS n'atteindront pas l'intérieur des widgets. La seule personnalisation prévue est la couleur de marque, réglée dans l'espace marchand. Un affichage réellement sur mesure passe par l'API publique — c'est exactement ce pour quoi elle est documentée.

7. Serveur MCP

MCP (Model Context Protocol) expose les mêmes capacités que l'API, sous une forme qu'un assistant IA peut découvrir seul. Là où un développeur lit une documentation, écrit l'authentification et interprète le JSON, l'assistant demande la liste des outils, lit leurs descriptions et les appelle.

Concrètement : le marchand branche son assistant sur ce serveur, puis écrit « quels avis n'ont pas encore de réponse ? » ou « réponds à celui-ci en t'excusant pour le délai ». Personne n'a écrit de code d'intégration.

7.1 Brancher un assistant : le jeton

C'est la voie normale, et la seule qui ne demande rien d'installé. Le marchand crée un jeton dans son espace — Réglages · Collecte, section « Brancher un assistant » —, puis le colle dans la configuration de son assistant avec l'adresse du serveur.

POST https://louis.guide/api/v1/mcp
Authorization: Bearer mcp_live_…
Content-Type: application/json

Forme usuelle des fichiers de configuration d'un client MCP :

{
  "mcpServers": {
    "avis-clients": {
      "url": "https://louis.guide/api/v1/mcp",
      "headers": { "Authorization": "Bearer mcp_live_…" }
    }
  }
}

Vérification en une commande, avant de brancher quoi que ce soit :

curl -X POST 'https://louis.guide/api/v1/mcp' \
  -H 'Authorization: Bearer mcp_live_…' \
  -H 'Content-Type: application/json' \
  --data-raw '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Ce que le jeton peut, et ce qu'il ne peut pas

7.2 Alternative : clé d'API et signature HMAC

Le même point d'entrée accepte l'authentification décrite au §2 : clé d'API et signature HMAC. Elle a un avantage réel — le secret ne quitte jamais le serveur du marchand — et un inconvénient qui la réserve aux intégrateurs : aucun client MCP ne sait recalculer un HMAC à chaque appel, ils ne posent que des en-têtes fixes.

Il faut donc un pont : un petit programme lancé par l'assistant, qui reçoit le JSON-RPC sur son entrée standard, le signe, l'envoie et rend la réponse. Node.js 18 ou plus récent, aucune dépendance. Enregistrez-le sous pont-mcp.js.

#!/usr/bin/env node
'use strict';

// Pont MCP : entrée standard (JSON-RPC) → API signée → sortie standard.
const crypto = require('crypto');
const readline = require('readline');

const BASE = process.env.LG_API_URL;
const CLE = process.env.LG_API_KEY;
const SECRET = process.env.LG_API_SECRET;
const CHEMIN = '/api/v1/mcp';

readline.createInterface({ input: process.stdin }).on('line', async (ligne) => {
  const corps = ligne.trim();
  if (!corps) return;

  let requete;
  try { requete = JSON.parse(corps); } catch (e) { return; }

  // Une notification n'a pas d'identifiant, et n'attend AUCUNE réponse :
  // en écrire une romprait le protocole côté client.
  const attendUneReponse = requete.id !== undefined && requete.id !== null;

  const ts = Math.floor(Date.now() / 1000).toString();

  // On signe la chaîne qu'on envoie, pas un objet réencodé : réencoder
  // produirait tôt ou tard un échappement différent, donc un 401 inexplicable.
  const signature = crypto.createHmac('sha256', SECRET)
    .update(ts + 'POST' + CHEMIN + corps)
    .digest('hex');

  try {
    const reponse = await fetch(BASE + CHEMIN, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Api-Key': CLE,
        'X-Timestamp': ts,
        'X-Signature': 'sha256=' + signature,
      },
      body: corps,
    });

    const texte = await reponse.text();
    if (attendUneReponse) process.stdout.write(texte + '\n');
  } catch (erreur) {
    if (attendUneReponse) {
      process.stdout.write(JSON.stringify({
        jsonrpc: '2.0',
        id: requete.id,
        error: { code: -32603, message: 'Pont MCP : ' + erreur.message },
      }) + '\n');
    }
  }
});

Déclaration côté client MCP (forme usuelle des fichiers de configuration) :

{
  "mcpServers": {
    "avis-clients": {
      "command": "node",
      "args": ["/chemin/absolu/vers/pont-mcp.js"],
      "env": {
        "LG_API_URL": "https://louis.guide",
        "LG_API_KEY": "ak_live_5c2f81b0",
        "LG_API_SECRET": "sk_live_3f9c1a7e5b2d48a6"
      }
    }
  }
}

Le secret ne sort pas de la machine. Il sert à signer localement ; ce qui part sur le réseau, c'est la signature. Un chemin absolu est indispensable : l'assistant ne lance pas le programme depuis le dossier où vous l'avez écrit.

Pour vérifier le pont avant de brancher quoi que ce soit, envoyez-lui une ligne à la main. Une liste d'outils doit revenir :

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | LG_API_URL='https://louis.guide' LG_API_KEY='ak_live_…' LG_API_SECRET='sk_live_…' node pont-mcp.js

7.3 Méthodes

POST /api/v1/mcp

{"jsonrpc":"2.0","id":1,"method":"initialize"}

HTTP/1.1 200 OK

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "avis-clients", "version": "1.0.0" }
  }
}

7.4 Les trois outils

Deux lisent, un écrit. La ligne de partage n'est pas technique : lire des avis ne présente aucun risque, tandis que publier une réponse fait parler le marchand en public sur une page que nous hébergeons — une formulation malheureuse sur un avis sensible, et c'est une capture d'écran qui circule.

C'est pourquoi tools/list ne renvoie que deux outils lorsque l'appelant présente un jeton en lecture seule. Ne codez donc pas la liste en dur : demandez-la, et n'annoncez au marchand que ce qu'elle contient.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "lister_avis",
    "arguments": { "note_max": 3, "sans_reponse": true, "limite": 10 }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"avis\":[{\"id\":\"9f1c2b3d-…\",\"note\":2,\"titre\":\"Colis abîmé\",\"commentaire\":\"…\",\"langue\":\"fr\",\"auteur\":\"Claire M.\",\"publie_le\":\"2026-08-13\",\"deja_repondu\":false}],\"total\":1}"
      }
    ],
    "isError": false
  }
}

{
  "boutique": "Tissu Fiesta",
  "note_moyenne": 4.6,
  "avis_publies": 318,
  "repartition": { "1": 4, "2": 6, "3": 18, "4": 91, "5": 199 },
  "avis_produit": 127
}

{
  "avis_id": "9f1c2b3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
  "publiee": false,
  "message": "Réponse enregistrée en brouillon. Le marchand doit la valider dans son espace avant qu'elle ne paraisse."
}

7.5 Erreurs

Toujours un statut HTTP 200, y compris en cas d'erreur : en JSON-RPC, l'erreur voyage dans le corps. Un 4xx ferait croire au client que le transport a échoué, et la plupart réessaieraient au lieu d'afficher le message.

Seule exception : l'authentification, refusée avant d'atteindre la couche JSON-RPC. Elle répond avec l'enveloppe d'erreur habituelle de l'API.

Les erreurs métier d'un outil ne sont pas des erreurs JSON-RPC : la réponse reste un résultat, avec isError: true et un objet { "erreur": "…" } dans le texte. C'est le cas d'un avis introuvable, d'un contenu vide, ou d'une réponse tentée avec un jeton en lecture seule. L'assistant peut ainsi l'expliquer au marchand au lieu d'annoncer une panne.

8. Webhooks entrants

Les deux points d'entrée ci-dessous existent pour des appelants précis — notre opérateur SMS et notre prestataire de paiement. Aucun intégrateur n'a à les appeler, et aucun ne peut le faire : ils sont l'un et l'autre fermés par un secret qui n'est pas distribué.

9. Limites de débit

Les limites sont calculées en fenêtre glissante : pas de compteur qui se remet à zéro à l'heure ronde, donc pas de rafale possible en début de période.

L'API CMS n'est pas bridée, ce qui n'autorise pas tout

Aucune limite de débit n'est appliquée aujourd'hui aux endpoints signés (/api/v1/cms/ et MCP) : ils sont authentifiés, et le volume réel est borné par le quota de sollicitations du marchand. Traitez quand même le 429 — une limite pourra être ajoutée, et une intégration qui ne sait pas la lire tombera en panne le jour où elle apparaîtra.

En pratique : transmettez les commandes au fil de l'eau plutôt qu'en lot nocturne de plusieurs milliers, et interrogez les avis à l'heure plutôt qu'à la minute (§8). Un volume anormal est visible de notre côté et déclenche une prise de contact, pas une coupure silencieuse.

Ce que renvoie un dépassement

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Remaining: 0

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Trop de requêtes. Réessayez dans quelques instants."
  }
}

Retry-After donne le nombre de secondes à attendre. Respectez-le : réessayer immédiatement ne fait que consommer la fenêtre suivante. Une temporisation exponentielle, plafonnée à une minute, suffit à tous les cas décrits ici.

Le sondage de raccordement fait exception et répond { "status": "rate_limited" } : c'est le même événement, exprimé dans le vocabulaire d'un endpoint que le module interroge en boucle.

10. Codes d'erreur communs

Deux formats, et un seul à traiter dans la plupart des cas

Partout dans l'API, une erreur porte la même enveloppe :

{
  "error": {
    "code": "invalid_api_key",
    "message": "Clé d'API inconnue, révoquée ou expirée."
  }
}

Le code est stable et destiné à votre programme ; le message est destiné à l'humain qui débogue et peut être reformulé sans préavis. Ne construisez jamais votre logique sur le texte du message.

Une seule exception : POST /cms/orders, servi par une couche différente, renvoie ses erreurs de validation sous forme de liste de violations. Un client robuste lit donc error.code s'il existe, et se rabat sur violations sinon.

Statuts HTTP

Récapitulatif des codes

Trois symptômes, et par où commencer

Si rien de tout cela ne colle

Écrivez-nous depuis l'espace marchand en joignant trois choses : le chemin appelé, l'horodatage de la requête, et le code d'erreur reçu. Avec ces trois éléments, la requête se retrouve dans les journaux ; sans eux, la seule réponse possible est de vous demander de les fournir.

↑ Revenir au début