Documentación de la API

1. Introducción

La plataforma expone tres canales distintos. No comparten ni el mismo público, ni el mismo régimen de autenticación, ni los mismos límites. Elegir el correcto es la primera decisión de una integración.

Direcciones base

Todas las URL de esta página son relativas a la dirección de la API. Un módulo solo debe conocer esa: las demás direcciones se le devuelven mediante GET /api/v1/cms/me, lo que le evita adivinarlas y nos permite cambiarlas sin actualizar nada en casa de los comerciantes.

Convenciones

• Formato — JSON tanto de entrada como de salida, codificado en UTF-8. La cabecera Content-Type: application/json se espera en toda petición que lleve cuerpo.
• Nomenclatura — serpiente en minúsculas (external_order_id, experienced_at), la convención dominante de las API que consumen los integradores de PHP y JavaScript.
• Fechas — ISO 8601 con zona horaria explícita en la entrada (2026-08-01T14:22:00+02:00). En la salida, las fechas completas usan el mismo formato; las fechas públicas de una reseña se reducen al día (2026-08-01) porque ningún widget muestra la hora.
• Importes — transmitidos como cadena ("129.90") y nunca como número en coma flotante: un céntimo perdido al redondear en un pedido se convierte en una diferencia de facturación.
• Identificadores — los objetos que creamos llevan un UUID permanente. Los suyos (pedido, producto, variante) siguen siendo suyos: nunca los reescribimos.
• Errores — siempre el mismo sobre { "error": { "code": …, "message": … } }. El code es estable y está destinado a su programa, el message al humano que depura. Véase §10.
• Versionado — el /v1 de la ruta es un contrato. Puede añadirse un campo opcional en cualquier momento; ningún campo existente será renombrado, eliminado ni convertido en obligatorio. Una ruptura saldría en /v2, quedando la versión anterior aún servida — los módulos corren en casa de los comerciantes y nadie puede actualizarlos a distancia. Su código debe por tanto ignorar los campos que no conoce en lugar de fallar al verlos.

Obtener una clave de API

1. Cree una cuenta de comerciante en el área del comerciante.
2. Confirme la dirección de correo y abra a continuación la sección de claves de API.
3. Anote el secreto: solo se muestra una vez. Una vez perdido no se recupera — se crea una clave nueva y se revoca la antigua.

Un módulo de instalación no necesita esta maniobra: abre él mismo una solicitud de conexión que el comerciante valida con un clic. Véase §3.

2. Autenticación

La API CMS y el servidor MCP usan el mismo mecanismo: una clave que dice quién llama, y una firma que prueba que quien llama posee el secreto. Son dos cosas distintas.

2.1 La firma, paso a paso

Paso 1 — Las tres cabeceras

Paso 2 — Construir la carga que se va a firmar

Cuatro piezas concatenadas sin separador, exactamente en este orden:

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

Paso 3 — Calcular

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

Paso 4 — Comprobar su implementación con este ejemplo

Estos valores son fijos y la firma mostrada es realmente la de estos datos: si su código produce otra cosa, el problema está en su código, no en el nuestro.

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

Carga que se va a firmar (una sola línea, sin espacios añadidos):

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

Resultado esperado:

X-Signature: sha256=8a9c0de10516226f965465704902e00c666892b483b45b361f4536a6b2ee36e9

El mismo cálculo en una línea 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 y no echo: este último añade un salto de línea final, que cambia la firma.

Paso 5 — Una llamada completa con 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 y no --data: el segundo interpreta ciertos caracteres y puede modificar el cuerpo enviado, invalidando así la firma.

2.2 Ejemplo en PHP

El cliente mínimo, sin dependencias. Es el mismo mecanismo que el de los módulos de PrestaShop y WooCommerce, reducido a lo esencial.

<?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 Las cuatro trampas

Cuatro causas explican la práctica totalidad de los signature_mismatch. Vistas desde fuera se parecen todas — de ahí el interés de descartarlas en este orden.

1. El cuerpo se recodificó después de la firma. El caso más frecuente y el más difícil de ver: un array serializado dos veces da dos cadenas distintas en cuanto contiene un acento o una barra (JSON_UNESCAPED_UNICODE, JSON_UNESCAPED_SLASHES, orden de las claves). Firme la cadena, envíe esa cadena, no la reconstruya jamás.
2. La ruta firmada lleva un prefijo que no debería tener. La ruta firmada es /api/v1/cms/orders, aunque la API se sirva desde https://ejemplo.es/plataforma/api/v1/cms/orders. El prefijo de instalación pertenece a la dirección base. A la inversa, tampoco firme la URL completa con su esquema y su host.
3. El reloj del servidor se ha desviado. Tolerancia: 300 segundos de desfase, en un sentido como en otro. Más allá, la respuesta es timestamp_out_of_range y su mensaje indica el desfase medido en segundos — exactamente la información que hay que dar a su alojador. Este caso se manifiesta a menudo como una integración que "ayer funcionaba".
4. Faltan el método o el prefijo. El método entra en la carga en mayúsculas, y el valor de X-Signature empieza por sha256=. Un HMAC desnudo, sin prefijo, se rechaza.

Reproducción y ventana de validez

La carga firmada cubre la marca de tiempo, el método, la ruta y el cuerpo. Omitir uno de ellos abriría una brecha: sin la ruta, una firma válida para POST /orders sería reproducible en DELETE /orders; sin la marca de tiempo, la petición sería reproducible indefinidamente.

La ventana de 300 segundos es lo que acota la reproducción: una petición interceptada no puede reemitirse más allá. No hay diccionario de firmas ya vistas — dentro de esa ventana una petición idéntica se acepta por tanto dos veces. Eso no afecta a la transmisión de pedidos, que es idempotente por external_order_id: la segunda recibe el pedido ya registrado y no envía un segundo correo.

Respuestas de autenticación

Todas estas respuestas llevan el estado 401.

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

{
  "error": {
    "code": "timestamp_out_of_range",
    "message": "Marca de tiempo fuera de tolerancia: +412 s de desfase con nuestro servidor (máximo 300 s). El reloj de su servidor está probablemente desincronizado."
  }
}

3. Conectar una tienda

Estos dos endpoints permiten a un módulo recuperar una clave sin que el comerciante tenga que copiar nada. El módulo abre una solicitud, muestra un enlace, el comerciante valida en su navegador, y el módulo recibe su clave y su secreto en la lectura siguiente.

Van sin autenticación, por construcción. La seguridad no descansa en una identidad sino en tres cosas: la solicitud no obtiene nada mientras un comerciante conectado no la haya validado, el token de sondeo nunca sale del servidor de la tienda, y el secreto se entrega una sola vez. Lo peor que puede producir una llamada malintencionada es una solicitud pendiente que nadie aprobará — y que caduca en un cuarto de hora.

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 (firmada)

El canal de las integraciones de servidor: módulos de comercio electrónico, ERP, CRM, herramientas internas. Todas las URL van precedidas de https://louis.guide.

Lecturas: basta la clave. Escrituras: clave + firma. El detalle del cálculo está en §2. Las fichas siguientes recuerdan el régimen de cada una con una insignia.

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/es/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 pública

Solo lectura, sin autenticación, en /api/v1/public/. Es lo que consumen los widgets, y lo que puede consumir cualquier visualización a medida.

El {slug} de las rutas es el identificador público del comerciante — el de su página pública, visible en urls.profile que devuelve /cms/me.

Lo que protege una API sin clave

No hay identidad que comprobar: este código se ejecuta en casa de los visitantes de una tienda, ningún secreto puede vivir ahí. La protección descansa por tanto en otras tres cosas, que hay que conocer antes de integrar.

• De aquí no sale ningún dato sensible. Ni correo, ni huella de correo, ni referencia de pedido, ni identificador interno. Un widget muestra reseñas públicas; todo lo que sale por este canal es legible por cualquiera.
• Caudal limitado a 60 peticiones por minuto y por dirección IP, en ventana deslizante. Una ficha de producto hace dos llamadas: eso deja 30 cargas por minuto desde una misma dirección — amplio para un visitante, estrecho para un aspirador de contenidos. Véase §9.
• CORS restringido a los dominios declarados del comerciante. Un comodín * autorizaría a cualquier sitio — competidor, comparador, falsificador — a mostrar las reseñas de cualquier comerciante como si fueran suyas.

Caché

Todas las respuestas son públicas y se guardan en caché: 60 segundos para las reseñas y las puntuaciones, 300 segundos para los ajustes de visualización. Es lo que permite absorber el tráfico de una tienda en promoción sin dimensionar para el pico. No construya una visualización que suponga la aparición instantánea de una reseña publicada.

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

HTTP/1.1 200 OK

{ "status": "ok" }

6. Widgets de visualización

Cuatro elementos HTML que colocar en una plantilla. Un solo script que cargar, ninguna dependencia, ninguna configuración: la dirección de la API se deduce de la URL del propio script.

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

El script se carga una vez por página, donde se quiera; los elementos pueden colocarse antes que él. Se sirve bajo /widget/v1/: una evolución incompatible saldría en /v2/ y este seguiría sirviéndose tal cual — vive en plantillas que nadie va a actualizar.

Los cuatro elementos

Atributos

Ejemplo completo en una ficha de producto

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

Lo que el comerciante gobierna sin usted

Los elementos leen /display al cargarse. Dos ajustes vienen de ahí en lugar de un atributo, y es deliberado: el comerciante puede colocar sus etiquetas de una vez por todas y luego cambiar de opinión desde su área sin reabrir la plantilla.

• La insignia flotante — encendida o apagada, a la derecha o a la izquierda, con su separación. <avis-flottant> colocado en la plantilla no muestra nada mientras el comerciante no la haya activado. Está apagada por defecto: nada debe aparecer en su sitio sin que lo haya pedido.
• El color de marca — aplicado a las superficies que lo admiten. Las estrellas conservan su ámbar, igual que el verde de «Compra verificada» y el ámbar de «Impugnada»: esos colores portan un sentido, no decoran, y repintarlos haría ilegible la puntuación en un comerciante cuya marca sea amarillo pálido o blanca.

Los ajustes se piden una sola vez por página, incluso con cuatro elementos: la petición en curso se comparte. Eso es lo que evita que el widget sea el script que ralentiza la ficha de producto — reproche fundado que cabe hacer a la mayoría de los módulos de reseñas.

Aislamiento respecto a la plantilla

Cada elemento renderiza su contenido en un shadow DOM: el CSS de la plantilla no se desborda sobre el widget, y el del widget no se desborda sobre la tienda. Ninguno de los dos sería aceptable en el otro sentido.

Corolario que conviene conocer antes de intentarlo: sus reglas CSS no alcanzarán el interior de los widgets. La única personalización prevista es el color de marca, ajustado en el área del comerciante. Una visualización realmente a medida pasa por la API pública — que es exactamente para lo que está documentada.

7. Servidor MCP

MCP (Model Context Protocol) expone las mismas capacidades que la API, en una forma que un asistente de IA puede descubrir por sí solo. Donde un desarrollador lee una documentación, escribe la autenticación e interpreta el JSON, el asistente pide la lista de herramientas, lee sus descripciones y las llama.

En concreto: el comerciante conecta su asistente a este servidor y luego escribe «¿qué reseñas no tienen respuesta todavía?» o «responde a esta disculpándote por el retraso». Nadie ha escrito código de integración.

7.1 Conectar un asistente: el token

Es la vía normal, y la única que no requiere nada instalado. El comerciante crea un token en su área — Ajustes · Recogida, sección «Conectar un asistente» — y luego lo pega en la configuración de su asistente junto con la dirección del servidor.

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

Forma habitual de los archivos de configuración de un cliente MCP:

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

Verificación en un solo comando, antes de conectar nada:

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

Lo que el token puede y lo que no puede

7.2 Alternativa: clave de API y firma HMAC

El mismo endpoint acepta la autenticación descrita en §2: clave de API y firma HMAC. Tiene una ventaja real — el secreto nunca sale del servidor del comerciante — y un inconveniente que la reserva a los integradores: ningún cliente MCP sabe recalcular un HMAC en cada llamada, solo ponen cabeceras fijas.

Hace falta por tanto un puente: un pequeño programa lanzado por el asistente, que recibe el JSON-RPC por su entrada estándar, lo firma, lo envía y devuelve la respuesta. Node.js 18 o más reciente, ninguna dependencia. Guárdelo como 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');
    }
  }
});

Declaración del lado del cliente MCP (forma habitual de los archivos de configuración):

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

El secreto no sale de la máquina. Sirve para firmar localmente; lo que sale a la red es la firma. Una ruta absoluta es indispensable: el asistente no lanza el programa desde la carpeta en la que usted lo escribió.

Para comprobar el puente antes de conectar nada, envíele una línea a mano. Debe volver una lista de herramientas:

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

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 Las tres herramientas

Dos leen, una escribe. La línea divisoria no es técnica: leer reseñas no presenta riesgo alguno, mientras que publicar una respuesta hace hablar al comerciante en público en una página que alojamos nosotros — una formulación desafortunada en una reseña delicada, y hay una captura de pantalla circulando.

Por eso tools/list devuelve solo dos herramientas cuando quien llama presenta un token de solo lectura. No codifique por tanto la lista en duro: pídala, y anuncie al comerciante únicamente lo que contiene.

{
  "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": "Respuesta guardada como borrador. El comerciante debe validarla en su área antes de que aparezca."
}

7.5 Errores

Siempre un estado HTTP 200, incluso en caso de error: en JSON-RPC el error viaja en el cuerpo. Un 4xx haría creer al cliente que el transporte ha fallado, y la mayoría reintentaría en lugar de mostrar el mensaje.

La única excepción: la autenticación, rechazada antes de alcanzar la capa JSON-RPC. Responde con el sobre de error habitual de la API.

Los errores de negocio de una herramienta no son errores JSON-RPC: la respuesta sigue siendo un resultado, con isError: true y un objeto { "erreur": "…" } en el texto. Es el caso de una reseña no encontrada, de un contenido vacío, o de una respuesta intentada con un token de solo lectura. El asistente puede así explicárselo al comerciante en lugar de anunciar una avería.

8. Webhooks entrantes

Los dos endpoints siguientes existen para llamantes concretos — nuestro operador de SMS y nuestro proveedor de pagos. Ningún integrador tiene que llamarlos, y ninguno puede hacerlo: ambos están cerrados por un secreto que no se distribuye.

9. Límites de caudal

Los límites se calculan sobre una ventana deslizante: sin contador que se ponga a cero en la hora en punto, y por tanto sin ráfaga posible al inicio de un periodo.

La API CMS no está limitada, lo que no lo autoriza todo

Hoy no se aplica ningún límite de caudal a los endpoints firmados (/api/v1/cms/ y MCP): están autenticados, y el volumen real está acotado por la cuota de solicitudes del comerciante. Trate de todos modos el 429 — podrá añadirse un límite, y una integración que no sepa leerlo se romperá el día en que aparezca.

En la práctica: transmita los pedidos sobre la marcha en lugar de en lotes nocturnos de varios miles, y consulte las reseñas cada hora en lugar de cada minuto (§8). Un volumen anómalo es visible por nuestra parte y provoca un contacto, no un corte silencioso.

Lo que devuelve un exceso

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

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Demasiadas peticiones. Inténtelo de nuevo dentro de unos instantes."
  }
}

Retry-After da el número de segundos que hay que esperar. Respételo: reintentar de inmediato solo consume la ventana siguiente. Una espera exponencial, con tope de un minuto, basta para todos los casos aquí descritos.

El sondeo de conexión es la excepción y responde { "status": "rate_limited" }: es el mismo suceso, expresado en el vocabulario de un endpoint que el módulo consulta en bucle.

10. Códigos de error comunes

Dos formatos, y solo uno que tratar en la mayoría de los casos

En toda la API, un error lleva el mismo sobre:

{
  "error": {
    "code": "invalid_api_key",
    "message": "Clave de API desconocida, revocada o caducada."
  }
}

El code es estable y está destinado a su programa; el message está destinado al humano que depura y puede reformularse sin aviso. No construya jamás su lógica sobre el texto del mensaje.

Una sola excepción: POST /cms/orders, servido por una capa distinta, devuelve sus errores de validación como una lista de violations. Un cliente robusto lee por tanto error.code si existe, y recurre a violations en caso contrario.

Estados HTTP

Resumen de los códigos

Tres síntomas, y por dónde empezar

Si nada de esto encaja

Escríbanos desde el área del comerciante adjuntando tres cosas: la ruta llamada, la marca de tiempo de la petición y el código de error recibido. Con esos tres elementos la petición se encuentra en los registros; sin ellos, la única respuesta posible es pedírselos.

↑ Volver al principio