Aller au contenu
UCP
Menu

Guide technique · Implémentation

Implémenter le UCP : guide complet pour marchands et développeurs

Vous souhaitez rendre votre boutique compatible avec le Universal Commerce Protocol pour être accessible aux agents IA ? Ce guide technique couvre les prérequis, les endpoints à exposer, l'intégration des paiements AP2, les tests de validation et les erreurs courantes à éviter.

Mis à jour : avril 2026 · Requête principale : implémenter UCP

Prérequis avant de commencer

Compatibilité plateforme

Si vous utilisez Shopify : vous avez une longueur d'avance. Shopify est co-fondateur du UCP et offre un support natif depuis le lancement du protocole en janvier 2026. L'essentiel est d'activer les fonctionnalités UCP dans votre Admin et de compléter vos données produits.

Pour WooCommerce, Magento, PrestaShop, Salesforce Commerce ou BigCommerce : les spécifications sont ouvertes sur le GitHub officiel UCP. Un développeur backend familier avec REST et JSON-RPC peut implémenter une intégration basique en 2 à 3 jours de travail.

Pour une solution propriétaire : l'implémentation directe est possible et documentée sur ucp.dev. Comptez 5 à 10 jours de développement pour une intégration complète avec tests.

Qualité des données produits requise

  • Complètes : nom, description, prix, devise, variantes (taille, couleur), poids, dimensions
  • Identifiées : GTIN/EAN ou SKU propriétaire documenté par produit
  • Actualisées : stocks synchronisés en quasi-temps-réel (délai maximum : quelques minutes)
  • Enrichies : politiques de retour structurées, délais de livraison par zone, attributs catégorie-spécifiques

Processeur de paiement compatible AP2

Le UCP s'appuie sur l'Agent Payments Protocol (AP2). Les processeurs compatibles sont Stripe, Adyen, Mastercard, Visa et American Express, tous partenaires fondateurs du UCP. Si vous utilisez l'un de ces processeurs avec une intégration à jour, le support AP2 nécessite une activation, pas une refonte technique.

Étape 1 : Exposer les endpoints de catalogue

Le UCP définit des endpoints REST standardisés que votre serveur doit exposer pour que les agents IA puissent interroger votre catalogue.

GET /ucp/v1/catalog

Retourne la liste de vos produits au format JSON-LD UCP. Chaque produit doit inclure : @type: "Product", sku ou gtin, name, description, offers (avec prix, devise, disponibilité), shippingDetails et returnPolicy.

GET /ucp/v1/inventory/{sku}

Disponibilité en temps réel d'un produit spécifique. Exigences de performance critiques : réponse en moins de 200ms, disponibilité minimum 99,5%. Un timeout entraîne l'exclusion directe de votre produit par l'agent IA au profit d'un concurrent.

POST /ucp/v1/checkout

Reçoit les instructions d'achat de l'agent IA et initie le processus de commande. Doit gérer : validation de l'identité (Identity Linking UCP), réservation du stock, initiation du paiement AP2 et génération de la confirmation de commande avec numéro de suivi.

Étape 2 : Implémenter l'Identity Linking

L'Identity Linking permet à un agent IA d'associer l'identité d'un utilisateur à votre système marchand sans que cet utilisateur ait besoin de se connecter manuellement à votre site lors de chaque achat.

L'utilisateur autorise une fois (dans l'interface de l'agent IA) le partage de ses informations de livraison et de contact. Ces informations sont ensuite transmises via des tokens signés cryptographiquement que vous vérifiez via l'API de vérification UCP. Votre système ne stocke jamais les données bancaires, uniquement le token d'identité vérifié.

Étape 3 : Configurer les paiements AP2

Pour Stripe : Dashboard → Paramètres → Paiements agentiques → Activer l'Agent Payments Protocol. Configurez les limites de transaction autorisées pour les paiements initiés par agents (montant max, catégories éligibles).

Pour Adyen : contactez votre account manager pour activer le profil AP2. Adyen exige une validation préalable de vos endpoints catalogue et inventaire avant d'activer les paiements agentiques.

Étape 4 : Exposer les endpoints Order Management

Le UCP impose un ensemble d'endpoints de gestion post-achat que les agents IA utilisent pour tenir l'utilisateur informé :

  • GET /ucp/v1/orders/{order_id}, statut de commande en temps réel
  • POST /ucp/v1/orders/{order_id}/cancel, annulation initiée par l'agent IA
  • GET /ucp/v1/orders/{order_id}/tracking, suivi de livraison

Étape 5 : Tests et validation

Le dépôt GitHub officiel (github.com/Universal-Commerce-Protocol/ucp) inclut une suite de tests de conformité et un simulateur d'agent IA. Avant mise en production :

  1. Lancer la suite de tests UCP sur tous les endpoints
  2. Tester les scénarios d'erreur (stock épuisé, paiement refusé, timeout)
  3. Valider l'Identity Linking avec un token de test officiel
  4. Vérifier les temps de réponse de l'endpoint inventaire sous charge
  5. Simuler un achat complet end-to-end avec le simulateur d'agent

Erreurs courantes à éviter

Timeouts non gérés. Un endpoint inventaire qui répond au-delà de 500ms sera marqué comme peu fiable. Utilisez un cache Redis ou équivalent pour les données d'inventaire fréquemment consultées.

Stocks non synchronisés. Indiquer « disponible » pour un produit épuisé génère une mauvaise expérience et dégrade votre réputation agentique. Implémentez des webhooks entre votre WMS et l'API UCP.

Politique de retour absente. Les agents IA comparent activement les politiques de retour entre marchands. Un champ returnPolicy manquant ou vide vous désavantage face à des concurrents mieux renseignés.

Absence de gestion des erreurs côté checkout. L'agent IA doit recevoir des codes d'erreur standardisés (stock épuisé, identité non vérifiée, paiement refusé) pour pouvoir proposer une alternative à l'utilisateur.

Ressources officielles