Note de référence
Commandes UCP : état, événements et retours
Le modèle Order d'UCP après le checkout : instantané courant, webhooks, fulfillment, remboursements, retours et attribution.
Publiée le . Rattachée à le commerce agentique.
Après un checkout terminé, UCP représente la commande comme un instantané complet de l’état courant. Le marchand renvoie la même structure lors d’une lecture synchrone et d’un événement webhook. L’agent n’a donc pas à reconstruire l’état depuis des fragments.
En bref
GET /orders/{id}renvoie l’état complet le plus récent.- Les événements de fulfillment forment un journal append-only.
- Les ajustements couvrent retours, remboursements, crédits et litiges.
Quel est le rôle de la ressource Order ?
La spécification Order sépare la transaction finalisée du suivi après achat. La ressource contient les lignes, les attentes de livraison, les événements, les ajustements et, si le marchand le souhaite, un instantané de l’attribution du checkout d’origine.
Chaque réponse doit contenir l’entité complète. Cette règle simplifie la reprise après
une perte d’événement : une nouvelle lecture suffit pour retrouver l’état courant. Le
permalink_url reste la référence pour l’expérience complète, notamment les opérations
hébergées par le marchand.
Comment lire une commande ?
La seule opération de lecture standardisée est GET /orders/{id}. L’accès doit être
authentifié avant toute réponse. UCP accepte plusieurs mécanismes, dont OAuth 2.0, mTLS,
clé API ou signatures de messages HTTP.
Deux scopes connus encadrent l’accès utilisateur :
dev.ucp.shopping.order:readpour lire les commandes appartenant au client ;dev.ucp.shopping.order:managepour les opérations après achat, comme une annulation ou un retour.
L’autorisation ne doit jamais reposer sur la seule connaissance de l’identifiant.
Événements de livraison et attentes
Les attentes décrivent ce que le marchand prévoit : fenêtre, destination, méthode ou quantité concernée. Les événements de fulfillment enregistrent ce qui s’est réellement passé. Ils référencent les lignes et peuvent inclure le suivi transporteur.
La spécification recommande un journal append-only. Des types courants existent, comme
processing, shipped, in_transit, delivered ou returned_to_sender, mais le champ
reste ouvert. Une plateforme doit donc afficher correctement un type inconnu au lieu de
l’écarter.
Comment représenter un retour ou un remboursement ?
Les ajustements sont indépendants du fulfillment. Ils peuvent intervenir avant, pendant
ou après la livraison. Les types sont ouverts ; les usages courants couvrent refund,
return, credit, price_adjustment, dispute et cancellation.
Les quantités et montants sont signés. Une réduction porte une valeur négative, un ajout une valeur positive. Un ajustement peut viser une ligne ou la commande entière, par exemple pour rembourser les frais de livraison.
Le journal append-only reste préférable. Si le système marchand ne conserve pas l’historique, il peut mettre à jour une entrée en place, mais il perd alors une partie de la traçabilité utile en cas de litige agentique.
Pourquoi les webhooks doivent-ils envoyer l’état complet ?
Le marchand pousse les changements vers une URL fournie par la plateforme. Le payload
est la même entité complète que lors de GET Order. Cette symétrie réduit les branches
de code et rend le traitement idempotent plus simple.
Les webhooks doivent être signés. Le destinataire ne dispose sinon d’aucun moyen fiable de prouver l’origine d’un événement serveur. Une plateforme doit vérifier la signature, dédupliquer l’événement puis remplacer son instantané local par le plus récent.
Checklist après achat
- Protéger chaque commande par une autorisation liée à son propriétaire.
- Renvoyer l’entité complète à chaque lecture et chaque webhook.
- Conserver les événements de fulfillment dans l’ordre.
- Utiliser des montants signés pour les ajustements.
- Signer tous les webhooks et dédupliquer leur traitement.
- Faire du
permalink_urlla voie de repli humaine.
Cette couche après achat complète le parcours décrit sur la page commerce agentique.
Sources
Revenir à le commerce agentique · Toutes les notes · Read in English