Ce qu'est un manifeste UCP, et quand il vaut mieux ne pas en publier

Un manifeste UCP est un fichier JSON situé à /.well-known/ucp qui indique aux agents d'achat IA ce que votre boutique sait faire et où l'appeler. Ce n'est pas un fichier marketing ni un geste symbolique : il déclare de vrais points de terminaison d'API et les clés publiques servant à vérifier vos messages signés. Ce guide explique ce que contient le fichier, ce qu'il ne contient pas, comment le servir depuis Shopify, et quand il vaut mieux ne pas en publier.

Ce qu'est UCP

Le Universal Commerce Protocol est une norme ouverte, publiée par Google sous licence Apache 2.0, pour la découverte des marchands par les machines. Là où llms.txt et agents.md décrivent une entreprise en prose qu'un assistant peut citer, UCP décrit une interface : les services qu'un agent peut appeler pour parcourir le catalogue, commander et suivre une commande, sans intervention humaine.

Le point d'entrée est une seule URL well-known. Un agent récupère https://votre-boutique.example/.well-known/ucp, lit le JSON et apprend quelle version du protocole vous parlez, quels points de terminaison appeler et comment vérifier que les messages qui se réclament de vous viennent bien de vous.

Ce que le fichier doit contenir

Deux clés obligatoires au premier niveau : ucp et signing_keys.

• ucp.version — la version du protocole, sous forme de date : "2026-04-08". Les versions UCP sont des dates, pas du SemVer.
• ucp.services — une correspondance entre un identifiant de service tel que dev.ucp.shopping et ses liaisons de transport : version, URL de spécification, transport (rest, mcp, a2a ou embedded), URL de schéma et le endpoint que l'agent doit appeler.
• ucp.capabilities — une correspondance des fonctionnalités au sein de ces services, comme dev.ucp.shopping.checkout, chacune avec sa version et son schéma. Les extensions déclarent leur capacité parente.
• signing_keys — des clés publiques au format JWK, servant à vérifier les webhooks et les messages authentifiés que vous signez (RFC 9421, HTTP Message Signatures). La spécification place ce champ au premier niveau, mais les manifestes générés par Shopify l'omettent entièrement : son absence est donc normale et non un défaut à corriger.

ucp.payment_handlers est facultatif. Si vous prenez en charge plusieurs versions du protocole, une correspondance supported_versions pointe vers des URL de profil spécifiques à chaque version.

Un manifeste minimal valide

{
  "ucp": {
    "version": "2026-04-08",
    "services": {
      "dev.ucp.shopping": [{
        "version": "2026-04-08",
        "spec": "https://ucp.dev/2026-04-08/specification/overview",
        "transport": "rest",
        "endpoint": "https://business.example.com/ucp/v1",
        "schema": "https://ucp.dev/2026-04-08/services/shopping/rest.openapi.json"
      }]
    },
    "capabilities": {
      "dev.ucp.shopping.checkout": [{
        "version": "2026-04-08",
        "spec": "https://ucp.dev/2026-04-08/specification/checkout",
        "schema": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json"
      }]
    }
  },
  "signing_keys": [{
    "kid": "business_2026",
    "kty": "EC", "crv": "P-256", "use": "sig", "alg": "ES256",
    "x": "…", "y": "…"
  }]
}

Notez ce qu'implique ce endpoint : c'est une URL réelle qu'un agent appellera. Un manifeste est une promesse portant sur une infrastructure qui doit exister.

Sur Shopify, vous en avez déjà un

C'est le point que la plupart des guides présentent de travers. Shopify a co-développé UCP avec Google et l'active par défaut sur les boutiques : votre vitrine sert donc déjà un manifeste à /.well-known/ucp sans aucune configuration de votre part. Vérifiez le vôtre :

curl -sSL https://votre-boutique.example/.well-known/ucp | jq .

Un manifeste Shopify réel déclare un transport mcp pointant vers https://votre-boutique.myshopify.com/api/ucp/mcp, une correspondance supported_versions, des capacités dont checkout, cart, fulfillment, discount, order ainsi que la recherche et la consultation du catalogue, et des gestionnaires de paiement comme Google Pay et Shop Pay. Vous n'écrivez rien de tout cela, et vous ne devriez pas chercher à le remplacer.

Sur Shopify, le travail consiste donc à vérifier, pas à rédiger : confirmez que le fichier résout sur votre domaine en production, qu'il survit à ce qui se trouve devant votre boutique, et que rien de ce que vous avez ajouté ne le bloque. Les cas où vous rédigez vous-même sont le headless et les front-ends personnalisés, où vous contrôlez le serveur web et où la plateforme ne sert pas le chemin à votre place. Là, une redirection d'URL ou un proxy d'application est la voie habituelle — et tout ce qui précède sur le fait de ne déclarer que des points de terminaison qui répondent reste valable.

Quand ne pas en publier

Un manifeste vide ou inventé est pire que pas de manifeste du tout. Si services annonce un point de terminaison qui ne répond pas, un agent vous découvre, l'appelle et échoue — un résultat plus mauvais qu'un 404 franc, qui lui dit immédiatement de se rabattre sur la lecture de vos pages.

Cela vaut aussi pour les sites qui ne sont pas des boutiques. Notre propre site vitrine renvoie délibérément un 404 sur /.well-known/ucp : il ne vend rien, il n'y a donc aucun point de terminaison à déclarer, et la spécification ne prévoit aucun moyen de dire « je ne suis pas un marchand ». Un fichier factice qui n'existe que pour faire passer un contrôle au vert est une case cochée, pas une préparation.

Comment vérifier le vôtre

Trois points, dans cet ordre : le fichier renvoie 200 à un client non authentifié, son contenu se parse comme du JSON, et chaque URL de services résout. Les contrôles du Pilier A de Sichta couvrent les deux premiers sous le contrôle A1 et rapportent le résultat séparément de vos autres constats : un manifeste manquant devient une ligne précise plutôt qu'un score à interpréter.

La spécification bouge encore — les versions sont des dates et le schéma évolue — traitez donc le manifeste comme quelque chose que vous régénérez, pas que vous écrivez une fois pour toutes.

En bref

Publiez un manifeste UCP lorsque vous disposez d'un point de terminaison commerce qu'un agent peut réellement appeler. Servez-le à /.well-known/ucp en JSON non authentifié, déclarez un endpoint et des signing_keys réels, et vérifiez-le avec un simple client HTTP plutôt qu'un navigateur. Si cette infrastructure n'existe pas encore, un 404 est la réponse honnête — et llms.txt et agents.md sont ce qui paie aujourd'hui.