Setup Request vs retour panier : comprendre la différence

Dans une intégration PunchOut, deux messages cXML font l’essentiel du travail : le PunchOutSetupRequest et le PunchOutOrderMessage. Ils sont souvent confondus dans les premières étapes d’un projet, alors qu’ils n’ont rien à voir.

Cet article clarifie qui les envoie, quand, et ce qui s’y joue concrètement.

Le PunchOutSetupRequest : l’ouverture de session

Le PunchOutSetupRequest est envoyé par le système d’achats vers la boutique du fournisseur, au tout début du parcours.

Son rôle : annoncer “un utilisateur de chez X veut entrer dans votre boutique pour faire ses courses, voici qui il est et où il faudra renvoyer son panier”.

Concrètement, il contient :

• les identifiants techniques de l’acheteur (blocs Credential)
• des informations sur l’utilisateur (nom, email, parfois rôle)
• une URL de retour (BrowserFormPost)
• éventuellement une devise, une langue, un pays

La boutique ne reçoit pas encore de panier. Elle reçoit une demande d’ouverture de session.

Sa réponse - le PunchOutSetupResponse - contient une URL de démarrage. Le système d’achats redirige alors l’utilisateur vers cette URL, et la session navigable commence.

Le PunchOutOrderMessage : le retour du panier

Le PunchOutOrderMessage est envoyé par la boutique vers le système d’achats, à la fin du parcours, quand l’utilisateur valide son panier.

Son rôle : transmettre “voici les articles, quantités, prix etc… que l’utilisateur a sélectionnés, importez ça dans votre processus d’approbation”.

Il contient :

• l’identité de la session originelle (rappel du contexte)
• la liste des articles (ItemIn), avec leur quantité, leur prix, leur description
• les codes produit attendus par l’acheteur (codes internes, UNSPSC, SKU fournisseur)
• les unités de mesure
• les taxes et autres données contractuelles

C’est ce message qui, une fois côté acheteur, alimente le panier interne pour validation.

Pourquoi la confusion est dangereuse

Un développeur qui démarre un projet PunchOut peut être tenté de tout traiter dans un seul flux : “je reçois le SetupRequest, j’authentifie, je gère le panier, je renvoie.”

Sauf que :

• le SetupRequest arrive avant que l’utilisateur ait vu un seul produit ;
• le PunchOutOrderMessage est construit plus tard, quand le panier existe ;
• la session doit être conservée entre les deux, parfois pendant plusieurs minutes ou plus.

Les bugs typiques viennent de cette confusion :

• session perdue entre l’entrée et la sortie (cookie mal posé, durée trop courte) ;
• URL de retour oubliée ou mal stockée (panier prêt mais nulle part où l’envoyer) ;
• mapping appliqué à la mauvaise étape (au SetupRequest au lieu du PunchOutOrderMessage) ;
• échanges non sécurisés entre les systèmes, ce qui expose les credentials et les données acheteurs en transit.

Comment Gatebold le traite

Côté Gatebold, ces deux messages sont des événements distincts dans un modèle de session explicite :

• le PunchOutSetupRequest ouvre une session, journalisée et observable ;
• la session porte le contexte (acheteur, utilisateur, return URL) jusqu’au panier ;
• le PunchOutOrderMessage est construit en s’appuyant sur le mapping de l’acheteur, validé, journalisé ;
• chaque échange est signé en HMAC-SHA256, les credentials sont chiffrés en AES-256-GCM, et aucun secret ne transite en clair entre les systèmes.

Si quelque chose dérape, on voit à quelle étape - pas une vague erreur indistincte. Et la sécurité est garantie de bout en bout, sans configuration supplémentaire côté client.

C’est exactement ce dont parle la page PunchOut.

En résumé

Message	Direction	Quand	Contient
PunchOutSetupRequest	Acheteur → Boutique	Début	Identité, URL de retour
PunchOutOrderMessage	Boutique → Acheteur	Fin (validation panier)	Articles, prix, codes

Deux messages, deux directions, deux moments. Les confondre, c’est se condamner à des heures de débogage. Les distinguer proprement, c’est la base d’une intégration PunchOut qui tient en production.

Si vous avez un cas concret en tête, nous pouvons en parler.