Le Cauchemar des 47 Étapes

Il y a de nombreuses étapes cachées dans un flux e-commerce UCP. Dans une vitrine classique, l'utilisateur clique sur des boutons et le navigateur lui montre ce qui s'est passé. Dans le monde UCP, l'intention d'un acheteur est interprétée par un assistant IA et acheminée via une passerelle commerciale vers les systèmes de catalogue, de paiement et de checkout—souvent sans aucune interface pour "montrer la vérité" quand quelque chose casse. C'est pourquoi les équipes s'appuient sur la modélisation des interactions (diagrammes de séquence) pour rendre le comportement piloté par API compréhensible et révisable avant l'implémentation.

Le commerce agentique semble "simple" dans les démos, mais en production, il devient une conversation invisible et multi-système difficile à raisonner et encore plus difficile à déboguer. La solution est de traiter le Universal Commerce Protocol (UCP) comme un système distribué et de cartographier le handshake de bout en bout avant de coder.

Ce que UCP Fournit Déjà

UCP est conçu autour de la découverte + négociation entre un agent et un marchand, plutôt que chaque développeur inventant des intégrations ad-hoc. Il définit des "capacités de base" (comme Checkout, Discovery, Fulfillment) pour que le commerce puisse être composé en couches au lieu de devenir un monolithe fragile.

UCP modélise également le checkout comme une machine à états. Le protocole gère explicitement des états comme incomplete, requires_escalation et ready_for_complete. Quand l'agent ne peut pas procéder de manière autonome (par exemple, informations de livraison manquantes), le serveur marchand répond avec une continue_url structurée. Cela permet à l'agent de transférer l'utilisateur vers une vue web sécurisée pour compléter la tâche, puis reprendre la conversation via un canal de protocole intégré (JSON-RPC 2.0).

En clair : UCP vous donne les primitives (négociation, états, échappatoires). Votre travail est l'orchestration, l'UX et la fiabilité.

Ce que le Développeur Construit Réellement (le "Code de Liaison")

Pendant que UCP gère le backend, vous devez encore construire le cerveau de l'agent. Votre code possède la prise de décision (formation des requêtes, classement des résultats), la gestion des états (réaction aux signaux incomplete), et la couche de confiance (collecte de la confirmation de paiement explicite).

Dans notre analyse architecturale, les plus grands risques apparaissent exactement là où le flux s'arrête ou bifurque :

Le Fossé de l'"Hallucination" : Et si le catalogue ne retourne aucun résultat ?
La Boucle des "Données Manquantes" : Et si l'utilisateur n'a pas fourni de code postal ?
Le Risque de l'"Auth Silencieuse" : L'utilisateur a-t-il vraiment dit "payer maintenant" ?

Ce ne sont pas des problèmes Shopify ; ce sont des problèmes d'orchestration. Et c'est pourquoi une carte visuelle est critique.

Les 47 Interactions : Qui Possède Quoi ?

Nous avons décomposé le flux d'achat standard en 47 étapes pour montrer exactement où commence et où finit votre responsabilité.

Phase	Étapes	Géré par UCP / Marchand	Géré par le Développeur (Côté Agent)
Intention → Recherche Structurée	1–6	Aucun. C'est la capture d'intention utilisateur en amont.	Transformer l'intention floue en `Catalog Query` stable. Logger les hypothèses. Éviter d'halluciner des contraintes.
Requête Catalogue → Produits	7–11	La Gateway répond avec les produits correspondants (ou ensembles vides).	Choisir une stratégie de requête. Gérer gracieusement les états sans résultat (boucle "Clarifier et Réessayer").
Sélection → Session Checkout	12–20	UCP crée l'ID de session et définit la machine à états du checkout.	Persister le `session_id`. Se préparer à gérer les changements d'état (pas juste "succès/échec").
Boucle Champs Requis	21–30	UCP signale `incomplete` ou `requires_escalation`.	Demander à l'utilisateur les champs manquants. Soumettre les mises à jour de manière idempotente. Re-demander les totaux.
Confirmation de Paiement	31–38	La collecte de paiement est déléguée aux handlers (Shop Pay ou autres).	Imposer une porte de confirmation explicite. Ne pas capturer de fonds sans signal utilisateur.
Statut Commande → Notifier	39–47	Le Store fait autorité pour le statut et les mises à jour de fulfillment.	Mapper les codes de statut vers votre UI. Implémenter des IDs de corrélation pour le traçage support.

Pourquoi FlowZap est le Bon Format pour Cela

La documentation pourrit. Les diagrammes statiques sont ignorés.

FlowZap résout cela avec le Mode Diagramme de Séquence. Vous définissez la logique une fois en code—cartographiant les handoffs exacts entre votre Agent et la Gateway UCP—et nous rendons deux vues automatiquement :

La Vue Architecte (Séquence) : Appels API précis, typage strict des participants (Shopper, Assistant, Gateway), et visualisation des boucles et états d'attente.
La Vue Stakeholder (Flux) : Une carte de parcours simplifiée qui explique ce qui se passe sans le bruit du protocole.

Cela garantit que votre PM, votre Lead Dev et votre équipe QA regardent tous la même source de vérité.

Ne Partez Pas de Zéro. Utilisez le Template.

Nous savons que vous ne voulez pas passer votre sprint à cartographier 47 étapes d'interaction. Donc nous avons fait le gros du travail pour vous.

Nous avons publié le Blueprint Shopify UCP comme template gratuit dans la bibliothèque FlowZap. Il est pré-chargé avec :

La Logique Complète : Les 47 étapes du flux d'achat standard, scriptées en code FlowZap éditable.
Propriété Annotée : Nous avons tagué les étapes comme // UCP Managed vs // Dev Required pour que vous puissiez voir instantanément votre surface d'implémentation.
États Critiques : Boucles pré-construites pour missing_info et payment_confirmation prêtes pour votre logique spécifique.

Télécharger le Template UCP .fz

Les Trois "Zones de Mort" (Où les Intégrations Échouent Généralement)

Le diagramme est long, mais les modes d'échec se regroupent dans des endroits prévisibles : traduction, collecte de données et confiance de paiement. Voici les trois zones qui méritent d'être sur-documentées (et sur-testées) car elles créent les bugs les plus coûteux.

Zone de Mort 1 : Le "Fossé de l'Hallucination" (Étapes 4–10)

L'assistant IA doit transformer une requête vague en requête structurée, puis la gateway interroge le catalogue du store et retourne les produits correspondants. Si le catalogue retourne "rien de pertinent", le pire comportement possible est que l'assistant "invente" une option avec confiance ; le comportement correct est de bifurquer vers la clarification ("couleur ?", "budget ?", "marque ?") et réessayer avec des contraintes plus serrées.

FlowZap aide ici car vous pouvez modéliser le retry comme une boucle de première classe, au lieu de l'enterrer dans une logique de prompt ad-hoc. FlowZap Code supporte même une syntaxe de fragment de boucle conçue pour exprimer la logique de retry de manière compacte, ce qui est exactement ce qu'est "clarifier et réessayer".

Zone de Mort 2 : La "Boucle des Données Manquantes" (Étapes 21–30)

Après l'initialisation du checkout, le store retourne les champs requis (adresse de livraison, option de livraison, email, etc.), et l'assistant doit mettre en pause le protocole pour demander à l'acheteur les données manquantes. C'est là que beaucoup de flux agentiques meurent en production : une réponse de champ manquant n'est pas une "erreur", c'est une transition d'état qui nécessite un prompt utilisateur et un état d'attente.

Le diagramme montre explicitement "demander à l'acheteur les infos manquantes", "attendre", puis "soumettre les détails acheteur", suivi de "recalculer les totaux" et "retourner le résumé de commande". Ce n'est pas du remplissage—ces étapes sont votre blueprint pour l'idempotence et pour prévenir les soumissions en double quand un utilisateur change d'avis en plein checkout.

Zone de Mort 3 : Le Risque du "Paiement Silencieux" (Étapes 31–38)

Le diagramme fait de la confirmation de paiement un handshake explicite : montrer un résumé de commande, demander confirmation, attendre, puis envoyer une intention de paiement et procéder à l'autorisation/capture. Cette séparation est un garde-fou : elle force une frontière claire entre "recommandation/conversation" et "mouvement d'argent".

Pour les développeurs, c'est là que les diagrammes de séquence gagnent leur place : il devient évident quel acteur est responsable de chaque action et exactement quand le processeur de paiement est invoqué. Il devient aussi évident où attacher les logs d'audit (ce qui a été montré dans le résumé, ce qui a été confirmé, et quand l'intention a été créée).

Le Résultat Final

Le commerce agentique ne consiste pas seulement à connecter un LLM à une API ; il s'agit de gérer une conversation complexe et asynchrone entre un utilisateur, un bot et un protocole bancaire rigide. La différence entre une "démo" et un "produit" est la grâce avec laquelle votre système gère le milieu désordonné—les retries, les adresses manquantes et les confirmations de paiement.

Arrêtez de deviner la machine à états. Forkez notre blueprint, cartographiez vos cas limites spécifiques, et donnez à votre équipe la visibilité dont elle a besoin pour livrer avec confiance.

Guide du Développeur pour Shopify UCP