Prérequis avant de commencer
Compatibilité plateforme
Shopify fournit ses propres surfaces Agent et Catalog. Les capacités disponibles et l'authentification dépendent de la surface et du compte : utilisez la documentation Shopify actuelle.
Pour WooCommerce, Magento, PrestaShop, Salesforce Commerce, BigCommerce ou une solution propriétaire, l'effort dépend des systèmes de catalogue, checkout, identité, paiement et commande déjà en place. Les schémas et bindings UCP officiels sont la source de vérité; la spécification ne publie pas de délai universel.
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
Paiement et périmètre AP2
UCP accepte plusieurs gestionnaires de paiement. AP2 est une extension optionnelle du checkout qui ajoute des Checkout Mandates et Payment Mandates signés. Vérifiez la prise en charge et la procédure dans la documentation actuelle de chaque prestataire.
É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.
POST /catalog/search
Recherche le catalogue avec le schéma JSON UCP versionné. Les identifiants, descriptions, prix, médias et disponibilités suivent les champs définis par la capacité Catalog négociée.
POST /catalog/lookup
Recherche des produits ou variantes par identifiant. La disponibilité est portée par les variantes et le checkout reste l'autorité pour le prix, l'éligibilité et le stock. Fixez un budget de performance adapté à votre service; la spécification n'impose pas les chiffres précédemment indiqués ici.
POST /checkout-sessions
Crée une session de checkout relativement à l'URL REST de base publiée dans le profil de l'entreprise. Les opérations de lecture, mise à jour, finalisation et annulation suivent le binding négocié.
É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'Identity Linking utilise OAuth 2.0 et des scopes déclarés. Implémentez la spécification actuelle de cette capacité et minimisez les données demandées; aucune API générique de vérification UCP ne remplace les contrôles de votre serveur d'autorisation.
Étape 3 : Configurer les paiements AP2
Quand AP2 est négocié, le Shopping Agent, le marchand, le Credential Provider et le Merchant Payment Processor valident les mandates, leur liaison au checkout et les reçus correspondant à leur rôle. La disponibilité et la configuration propres à un prestataire doivent être vérifiées dans sa documentation.
Étape 4 : Exposer les endpoints Order Management
Le binding REST actuel expose l'état courant de la commande et conserve le lien marchand comme expérience post-achat de référence :
GET /orders/{id}retourne la commande, ses événements de livraison et ses ajustements.- Les Order Event Webhooks peuvent pousser les changements du marchand vers la plateforme.
- Retours, annulations et autres actions suivent les capacités réellement proposées par le marchand.
Étape 5 : Tests et validation
Avant la mise en production, validez le binding et les schémas exacts négociés par les deux profils :
- Tester la découverte, les en-têtes de cache, la version et l'élagage des capacités
- Valider les réponses et erreurs contre les schémas versionnés
- Tester l'authentification, les scopes et les signatures HTTP lorsqu'elles sont utilisées
- Tester la charge du catalogue et du checkout selon vos objectifs de service
- Couvrir les parcours directs et autonomes pour les capacités réellement prises en charge
Erreurs courantes à éviter
Timeouts non gérés. Définissez des délais côté client et serveur, surveillez la latence et ne présentez pas le catalogue comme un engagement transactionnel.
Stocks non synchronisés. Revalidez prix et disponibilité au checkout, car le catalogue ne constitue pas un engagement.
Métadonnées incomplètes. N'annoncez que les versions, transports et extensions réellement pris en charge.
Résultats métier ignorés. Lisez le tableau UCP messages avant d'exploiter les données de l'opération.
Ressources officielles
- GitHub UCP :
github.com/Universal-Commerce-Protocol/ucp - Documentation officielle :
ucp.dev - Guide Agent Payments Protocol (AP2)
- Données structurées pour agents IA
- Checklist readiness marchand UCP