API-Dokumentation

1. Einführung

Die Plattform stellt drei getrennte Kanäle bereit. Sie teilen weder dasselbe Publikum noch dieselbe Authentifizierung noch dieselben Grenzen. Den richtigen zu wählen ist die erste Entscheidung einer Integration.

Basisadressen

Alle URLs dieser Seite beziehen sich auf die Adresse der API. Ein Modul muss nur diese kennen: die übrigen Adressen liefert ihm GET /api/v1/cms/me, was ihm das Raten erspart und uns erlaubt, sie zu ändern, ohne bei den Händlern irgendetwas zu aktualisieren.

Konventionen

• Format — JSON bei Ein- und Ausgabe, UTF-8-kodiert. Der Header Content-Type: application/json wird bei jeder Anfrage mit Body erwartet.
• Benennung — kleine Schlangenschreibweise (external_order_id, experienced_at), die vorherrschende Konvention der APIs, die PHP- und JavaScript-Integratoren nutzen.
• Datumsangaben — ISO 8601 mit ausdrücklicher Zeitzone bei der Eingabe (2026-08-01T14:22:00+02:00). Bei der Ausgabe haben vollständige Datumsangaben dasselbe Format; die öffentlichen Datumsangaben einer Bewertung sind auf den Tag reduziert (2026-08-01), weil kein Widget die Uhrzeit anzeigt.
• Beträge — als Zeichenkette übermittelt ("129.90") und nie als Gleitkommazahl: ein beim Runden verlorener Cent auf einer Bestellung wird zur Abrechnungsdifferenz.
• Bezeichner — die von uns angelegten Objekte tragen eine dauerhafte UUID. Ihre eigenen (Bestellung, Produkt, Variante) bleiben Ihre: wir schreiben sie niemals um.
• Fehler — immer derselbe Umschlag { "error": { "code": …, "message": … } }. Der code ist stabil und für Ihr Programm bestimmt, die message für den Menschen, der Fehler sucht. Siehe §10.
• Versionierung — das /v1 im Pfad ist ein Vertrag. Ein optionales Feld kann jederzeit hinzukommen; kein bestehendes Feld wird umbenannt, entfernt oder verpflichtend gemacht. Ein Bruch erschiene als /v2, während die alte Version weiter ausgeliefert wird — Module laufen bei den Händlern, und niemand kann sie aus der Ferne aktualisieren. Ihr Code muss daher Felder ignorieren, die er nicht kennt, statt bei ihrem Anblick zu scheitern.

Einen API-Schlüssel erhalten

1. Legen Sie ein Händlerkonto in dem Händlerbereich an.
2. Bestätigen Sie die E-Mail-Adresse und öffnen Sie dann den Abschnitt der API-Schlüssel.
3. Notieren Sie das Geheimnis: es wird nur einmal angezeigt. Ist es verloren, lässt es sich nicht wiederfinden — man legt einen neuen Schlüssel an und widerruft den alten.

Ein Installationsmodul braucht diesen Vorgang nicht: es öffnet selbst eine Anbindungsanfrage, die der Händler mit einem Klick bestätigt. Siehe §3.

2. Authentifizierung

Die CMS-API und der MCP-Server verwenden denselben Mechanismus: einen Schlüssel, der sagt, wer aufruft, und eine Signatur, die beweist, dass der Aufrufer das Geheimnis besitzt. Das sind zwei verschiedene Dinge.

2.1 Die Signatur, Schritt für Schritt

Schritt 1 — Die drei Header

Schritt 2 — Die zu signierende Nutzlast bilden

Vier Teile, ohne Trennzeichen aneinandergehängt, in genau dieser Reihenfolge:

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

Schritt 3 — Berechnen

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

Schritt 4 — Ihre Umsetzung an diesem Beispiel prüfen

Diese Werte sind festgelegt, und die gezeigte Signatur ist tatsächlich die dieser Daten: liefert Ihr Code etwas anderes, liegt das Problem in Ihrem Code, nicht in unserem.

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 !"}

Zu signierende Nutzlast (eine einzige Zeile, keine zusätzlichen Leerzeichen):

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

Erwartetes Ergebnis:

X-Signature: sha256=8a9c0de10516226f965465704902e00c666892b483b45b361f4536a6b2ee36e9

Dieselbe Berechnung in einer Shell-Zeile:

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 und nicht echo: Letzteres hängt einen Zeilenumbruch an, was die Signatur verändert.

Schritt 5 — Ein vollständiger Aufruf mit 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 und nicht --data: Letzteres interpretiert bestimmte Zeichen und kann den gesendeten Body verändern und damit die Signatur ungültig machen.

2.2 PHP-Beispiel

Der minimale Client, ohne Abhängigkeit. Es ist derselbe Mechanismus wie in den Modulen für PrestaShop und WooCommerce, auf das Wesentliche reduziert.

<?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 Die vier Fallen

Vier Ursachen erklären nahezu alle signature_mismatch. Von außen sehen sie alle gleich aus — daher lohnt es, sie in dieser Reihenfolge auszuschließen.

1. Der Body wurde nach dem Signieren neu kodiert. Der häufigste Fall und der am schwersten zu erkennende: ein zweimal serialisiertes Array ergibt zwei verschiedene Zeichenketten, sobald es einen Akzent oder einen Schrägstrich enthält (JSON_UNESCAPED_UNICODE, JSON_UNESCAPED_SLASHES, Reihenfolge der Schlüssel). Signieren Sie die Zeichenkette, senden Sie diese Zeichenkette, bauen Sie sie niemals neu auf.
2. Der signierte Pfad trägt ein Präfix, das er nicht haben dürfte. Der signierte Pfad lautet /api/v1/cms/orders, auch wenn die API von https://beispiel.de/plattform/api/v1/cms/orders ausgeliefert wird. Das Installationspräfix gehört zur Basisadresse. Umgekehrt signieren Sie auch nicht die vollständige URL mit Schema und Host.
3. Die Serveruhr geht falsch. Toleranz: 300 Sekunden Abweichung, in beide Richtungen. Darüber hinaus lautet die Antwort timestamp_out_of_range, und ihre Meldung nennt die gemessene Abweichung in Sekunden — genau die Angabe für Ihren Hoster. Dieser Fall zeigt sich oft als Integration, die "gestern noch funktionierte".
4. Die Methode oder das Präfix fehlt. Die Methode geht in Großbuchstaben in die Nutzlast ein, und der Wert von X-Signature beginnt mit sha256=. Ein nackter HMAC ohne Präfix wird abgelehnt.

Wiedereinspielen und Gültigkeitsfenster

Die signierte Nutzlast umfasst den Zeitstempel, die Methode, den Pfad und den Body. Eines davon wegzulassen risse eine Lücke auf: ohne den Pfad wäre eine für POST /orders gültige Signatur auf DELETE /orders wiederverwendbar; ohne den Zeitstempel wäre die Anfrage unbegrenzt wiederverwendbar.

Das Fenster von 300 Sekunden ist es, was das Wiedereinspielen begrenzt: eine abgefangene Anfrage kann darüber hinaus nicht erneut gesendet werden. Es gibt kein Verzeichnis bereits gesehener Signaturen — innerhalb dieses Fensters wird eine identische Anfrage also zweimal angenommen. Auf die Übermittlung von Bestellungen hat das keine Auswirkung, denn sie ist idempotent über external_order_id: die zweite erhält die bereits erfasste Bestellung und versendet keine zweite E-Mail.

Antworten der Authentifizierung

Alle diese Antworten tragen den Status 401.

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

{
  "error": {
    "code": "timestamp_out_of_range",
    "message": "Zeitstempel außerhalb der Toleranz: +412 s Abweichung zu unserem Server (höchstens 300 s). Die Uhr Ihres Servers ist vermutlich nicht synchron."
  }
}

3. Einen Shop anbinden

Diese beiden Endpunkte erlauben es einem Modul, einen Schlüssel zu beziehen, ohne dass der Händler irgendetwas abtippen muss. Das Modul eröffnet eine Anfrage, zeigt einen Link, der Händler bestätigt im Browser, und das Modul erhält beim nächsten Lesezugriff seinen Schlüssel und sein Geheimnis.

Sie sind ohne Authentifizierung, und das ist Absicht. Die Sicherheit beruht nicht auf einer Identität, sondern auf drei Dingen: die Anfrage erhält nichts, solange kein angemeldeter Händler sie bestätigt hat, das Abfrage-Token verlässt den Server des Shops nie, und das Geheimnis wird nur ein einziges Mal übergeben. Das Schlimmste, was ein böswilliger Aufruf bewirken kann, ist eine offene Anfrage, die niemand bestätigt — und die nach einer Viertelstunde verfällt.

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. CMS-API (signiert)

Der Kanal der Serverintegrationen: E-Commerce-Module, ERP, CRM, interne Werkzeuge. Allen URLs ist https://louis.guide vorangestellt.

Lesen: der Schlüssel genügt. Schreiben: Schlüssel + Signatur. Die Berechnung ist in §2 ausgeführt. Die folgenden Einträge erinnern mit einem Abzeichen an die jeweilige Regelung.

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/de/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. Öffentliche API

Nur lesend, ohne Authentifizierung, unter /api/v1/public/. Das nutzen die Widgets, und das kann jede maßgeschneiderte Anzeige nutzen.

Der {slug} in den Pfaden ist der öffentliche Bezeichner des Händlers — derselbe wie auf seiner öffentlichen Seite, sichtbar in urls.profile, das /cms/me zurückgibt.

Was eine API ohne Schlüssel schützt

Es gibt keine Identität zu prüfen: dieser Code läuft bei den Besuchern eines Shops, dort kann kein Geheimnis leben. Der Schutz beruht daher auf drei anderen Dingen, die man vor der Integration kennen muss.

• Hier treten keine sensiblen Daten aus. Keine E-Mail, kein E-Mail-Fingerabdruck, keine Bestellreferenz, kein interner Bezeichner. Ein Widget zeigt öffentliche Bewertungen; alles, was über diesen Kanal austritt, ist für jedermann lesbar.
• Ratenbegrenzt auf 60 Anfragen pro Minute und IP-Adresse, über ein gleitendes Fenster. Eine Produktseite macht zwei Aufrufe: das lässt 30 Seitenaufrufe pro Minute von derselben Adresse zu — großzügig für einen Besucher, eng für einen Inhaltssauger. Siehe §9.
• CORS auf die hinterlegten Domains des Händlers beschränkt. Ein Platzhalter * erlaubte jeder Website — Wettbewerber, Vergleichsportal, Fälscher —, die Bewertungen eines beliebigen Händlers so anzuzeigen, als wären es die eigenen.

Cache

Alle Antworten sind öffentlich und werden zwischengespeichert: 60 Sekunden für Bewertungen und Noten, 300 Sekunden für die Anzeigeeinstellungen. Das fängt den Verkehr eines Shops in einer Aktion auf, ohne für die Spitze auslegen zu müssen. Bauen Sie keine Anzeige, die davon ausgeht, dass eine veröffentlichte Bewertung sofort erscheint.

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/de/m/tissufiesta"
}

HTTP/1.1 200 OK

{ "status": "ok" }

6. Anzeige-Widgets

Vier HTML-Elemente, die in ein Theme gesetzt werden. Ein einziges Skript zu laden, keine Abhängigkeit, keine Konfiguration: die Adresse der API wird aus der URL des Skripts selbst abgeleitet.

<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>

Das Skript wird einmal pro Seite geladen, wo Sie wollen; die Elemente dürfen davor stehen. Es wird unter /widget/v1/ ausgeliefert: eine unverträgliche Weiterentwicklung erschiene als /v2/, und dieses hier bliebe unverändert bedient — es lebt in Themes, die niemand aktualisieren wird.

Die vier Elemente

Attribute

Vollständiges Beispiel auf einer Produktseite

<!-- 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>

Was der Händler ohne Sie steuert

Die Elemente lesen beim Laden /display. Zwei Einstellungen kommen von dort statt aus einem Attribut, und das ist Absicht: der Händler kann seine Tags ein für alle Mal setzen und danach aus seinem Bereich heraus umentscheiden, ohne sein Theme wieder zu öffnen.

• Das schwebende Abzeichen — an oder aus, rechts oder links, mit seinem Randabstand. <avis-flottant> in der Vorlage zeigt nichts, solange der Händler es nicht eingeschaltet hat. Es ist standardmäßig aus: bei ihm darf nichts erscheinen, ohne dass er darum gebeten hat.
• Die Markenfarbe — auf die Flächen angewandt, die es zulassen. Die Sterne behalten ihr Bernstein, ebenso das Grün von "Geprüfter Kauf" und das Bernstein von "Bestritten": diese Farben tragen Bedeutung, sie schmücken nicht, und sie zu übermalen machte die Note bei einem Händler mit blassgelber oder weißer Marke unlesbar.

Die Einstellungen werden nur einmal pro Seite abgefragt, selbst bei vier Elementen: die laufende Anfrage wird geteilt. Das verhindert, dass das Widget zu dem Skript wird, das die Produktseite bremst — ein berechtigter Vorwurf an die meisten Bewertungsmodule.

Abschottung gegenüber dem Theme

Jedes Element rendert seinen Inhalt in einem Shadow DOM: das CSS des Themes greift nicht auf das Widget über, und das des Widgets nicht auf den Shop. Keines von beiden wäre in der anderen Richtung hinnehmbar.

Eine Folge, die man vor dem Versuch kennen sollte: Ihre CSS-Regeln erreichen das Innere der Widgets nicht. Die einzige vorgesehene Anpassung ist die Markenfarbe, eingestellt im Händlerbereich. Eine wirklich maßgeschneiderte Anzeige läuft über die Öffentliche API — genau dafür ist sie dokumentiert.

7. MCP-Server

MCP (Model Context Protocol) stellt dieselben Fähigkeiten bereit wie die API, in einer Form, die ein KI-Assistent selbst entdecken kann. Wo ein Entwickler eine Dokumentation liest, die Authentifizierung schreibt und das JSON auslegt, fragt der Assistent die Liste der Werkzeuge ab, liest ihre Beschreibungen und ruft sie auf.

Konkret: der Händler schließt seinen Assistenten an diesen Server an und schreibt dann "welche Bewertungen haben noch keine Antwort?" oder "antworte auf diese und entschuldige dich für die Verzögerung". Niemand hat Integrationscode geschrieben.

7.1 Einen Assistenten anschließen: das Token

Das ist der normale Weg und der einzige, der nichts Installiertes verlangt. Der Händler erstellt in seinem Bereich ein Token — Einstellungen · Sammlung, Abschnitt "Einen Assistenten anschließen" — und fügt es dann zusammen mit der Serveradresse in die Konfiguration seines Assistenten ein.

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

Übliche Form der Konfigurationsdatei eines MCP-Clients:

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

Prüfung mit einem Befehl, bevor Sie irgendetwas anschließen:

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"}'

Was das Token kann und was nicht

7.2 Alternative: API-Schlüssel und HMAC-Signatur

Derselbe Endpunkt akzeptiert die in §2 beschriebene Authentifizierung: API-Schlüssel und HMAC-Signatur. Sie hat einen echten Vorteil — das Geheimnis verlässt den Server des Händlers nie — und einen Nachteil, der sie Integratoren vorbehält: kein MCP-Client kann bei jedem Aufruf einen HMAC neu berechnen, sie setzen nur feste Header.

Es braucht also eine Brücke: ein kleines Programm, das vom Assistenten gestartet wird, das JSON-RPC auf seiner Standardeingabe empfängt, es signiert, sendet und die Antwort zurückgibt. Node.js 18 oder neuer, keine Abhängigkeit. Speichern Sie es als 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');
    }
  }
});

Eintrag auf Seite des MCP-Clients (übliche Form der Konfigurationsdateien):

{
  "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"
      }
    }
  }
}

Das Geheimnis verlässt die Maschine nicht. Es dient dazu, lokal zu signieren; was ins Netz geht, ist die Signatur. Ein absoluter Pfad ist unerlässlich: der Assistent startet das Programm nicht aus dem Ordner, in dem Sie es geschrieben haben.

Um die Brücke zu prüfen, bevor Sie irgendetwas anschließen, geben Sie ihr von Hand eine Zeile. Es sollte eine Liste von Werkzeugen zurückkommen:

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 Methoden

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 Die drei Werkzeuge

Zwei lesen, eines schreibt. Die Trennlinie ist nicht technisch: Bewertungen zu lesen birgt kein Risiko, während das Veröffentlichen einer Antwort den Händler öffentlich sprechen lässt, auf einer Seite, die wir betreiben — eine unglückliche Formulierung bei einer heiklen Bewertung, und ein Bildschirmfoto macht die Runde.

Deshalb gibt tools/list nur zwei Werkzeuge zurück, wenn der Aufrufer ein Nur-Lese-Token vorlegt. Verdrahten Sie die Liste also nicht fest: fragen Sie sie ab, und kündigen Sie dem Händler nur an, was darin steht.

{
  "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": "Antwort als Entwurf gespeichert. Der Händler muss sie in seinem Bereich freigeben, bevor sie erscheint."
}

7.5 Fehler

Immer ein HTTP-Status 200, auch im Fehlerfall: bei JSON-RPC reist der Fehler im Body. Ein 4xx ließe den Client glauben, der Transport sei fehlgeschlagen, und die meisten versuchten es erneut, statt die Meldung anzuzeigen.

Die einzige Ausnahme: die Authentifizierung, abgelehnt bevor die JSON-RPC-Schicht erreicht wird. Sie antwortet mit dem gewohnten Fehlerumschlag der API.

Die fachlichen Fehler eines Werkzeugs sind keine JSON-RPC-Fehler: die Antwort bleibt ein Ergebnis, mit isError: true und einem Objekt { "erreur": "…" } im Text. Das gilt für eine nicht gefundene Bewertung, einen leeren Inhalt oder eine mit einem Nur-Lese-Token versuchte Antwort. Der Assistent kann es so dem Händler erklären, statt eine Störung zu vermelden.

8. Eingehende Webhooks

Die beiden folgenden Endpunkte bestehen für bestimmte Aufrufer — unseren SMS-Anbieter und unseren Zahlungsdienstleister. Kein Integrator muss sie aufrufen, und keiner kann es: beide sind durch ein Geheimnis verschlossen, das nicht verteilt wird.

9. Ratenbegrenzungen

Die Grenzen werden über ein gleitendes Fenster berechnet: kein Zähler, der zur vollen Stunde auf null springt, und damit kein möglicher Ausbruch zu Beginn eines Zeitraums.

Die CMS-API ist nicht gedrosselt, was nicht alles erlaubt

Auf die signierten Endpunkte (/api/v1/cms/ und MCP) wird heute keine Ratenbegrenzung angewandt: sie sind authentifiziert, und das tatsächliche Volumen ist durch das Einladungskontingent des Händlers begrenzt. Behandeln Sie den 429 dennoch — eine Grenze kann hinzukommen, und eine Integration, die sie nicht lesen kann, fällt an dem Tag aus, an dem sie erscheint.

In der Praxis: übermitteln Sie Bestellungen laufend statt in nächtlichen Stapeln von mehreren Tausend, und fragen Sie Bewertungen stündlich statt minütlich ab (§8). Auffälliges Volumen ist auf unserer Seite sichtbar und führt zu einer Kontaktaufnahme, nicht zu einer stillen Abschaltung.

Was eine Überschreitung zurückgibt

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

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Zu viele Anfragen. Versuchen Sie es in wenigen Augenblicken erneut."
  }
}

Retry-After gibt die Anzahl der Sekunden an, die zu warten sind. Halten Sie sich daran: sofort erneut zu versuchen verbraucht nur das nächste Fenster. Ein exponentielles Zurückweichen, bei einer Minute gedeckelt, genügt für alle hier beschriebenen Fälle.

Das Abfragen bei der Anbindung bildet die Ausnahme und antwortet { "status": "rate_limited" }: es ist dasselbe Ereignis, ausgedrückt im Vokabular eines Endpunkts, den das Modul in einer Schleife abfragt.

10. Gängige Fehlercodes

Zwei Formate, und meist nur eines zu behandeln

Überall in der API trägt ein Fehler denselben Umschlag:

{
  "error": {
    "code": "invalid_api_key",
    "message": "API-Schlüssel unbekannt, widerrufen oder abgelaufen."
  }
}

Der code ist stabil und für Ihr Programm bestimmt; die message ist für den Menschen bestimmt, der Fehler sucht, und kann ohne Ankündigung umformuliert werden. Bauen Sie Ihre Logik niemals auf den Text der Meldung.

Eine einzige Ausnahme: POST /cms/orders, von einer anderen Schicht bedient, gibt seine Validierungsfehler als Liste von violations zurück. Ein robuster Client liest also error.code, sofern vorhanden, und greift sonst auf violations zurück.

HTTP-Status

Übersicht der Codes

Drei Symptome, und wo man anfängt

Wenn nichts davon passt

Schreiben Sie uns aus dem Händlerbereich und fügen Sie drei Dinge bei: den aufgerufenen Pfad, den Zeitstempel der Anfrage und den erhaltenen Fehlercode. Mit diesen dreien lässt sich die Anfrage in den Protokollen finden; ohne sie bleibt als einzige Antwort, Sie danach zu fragen.

↑ Zurück zum Anfang