Spécifications d’intégration PunchOut pour boutiques sur mesure

1. Configuration dans PunchOut Rocket

Site e-commerce

Les chemins des endpoints sont ajoutés tels quels à Site URL et doivent donc commencer par /. Exemple : Site URL https://your-store.example.com + /api/punchout/clone → https://your-store.example.com/api/punchout/clone.

Les bons de commande (section 6) et paniers prédéfinis sont inclus dans le forfait Premium et l’essai gratuit : votre forfait les active sur le site et la page du client final affiche alors les sections Orders et Predefined Carts. Les confirmations et avis d’expédition (sections 7–8) nécessitent aussi l’option OC & ASN.

Client final

Chaque entreprise cliente est un client final de votre site. Outre ses identifiants de protocole (identités cXML et shared secret, ou utilisateur et mot de passe OCI), ces champs concernent votre boutique :

Le reste des pages du site et du client final fonctionne comme pour les autres plateformes : consultez la documentation.

2. Endpoint de clonage

Chemin par défaut : /api/punchout/clone. Appelé lorsqu’un client ouvre votre boutique depuis son système d’achat. Votre boutique crée (ou réutilise) un utilisateur cloné de username, lié à cette session PunchOut, et retourne une URL SSO qui connecte cet utilisateur (section 3).

Corps de la requête

quantity et price sont des chaînes : convertissez-les avant utilisation.

Requête : création avec un article sélectionné

{
  "username": "buyer123",
  "api_key": "site-api-key-abc",
  "session_token": "sess-012345",
  "operation": "create",
  "end_customer_id": 2,
  "gateway_base_url": "https://middleware.example.com",
  "selected_item": {
    "supplier_part_id": "X-100",
    "supplier_part_auxiliary_id": "19853"
  }
}

Requête : edit, avec le panier à restaurer

{
  "username": "buyer123",
  "api_key": "site-api-key-abc",
  "session_token": "sess-67890",
  "operation": "edit",
  "end_customer_id": 2,
  "gateway_base_url": "https://middleware.example.com",
  "cart_items": [
    {"sku": "ABC-001", "product_id": "19852", "quantity": "2", "price": "15.95",
     "description": "Example description", "currency": "EUR"},
    {"sku": "XYZ-002", "product_id": "19854", "quantity": "1", "price": "249.00",
     "description": "Another example description", "currency": "EUR"}
  ]
}

Réponse de succès

HTTP 2xx

HTTP 200
{
  "status": "success",
  "sso_url": "https://your-store.example.com/punchout/sso?token=eyJ..."
}

sso_url est le seul champ lu : il est obligatoire et doit être une URL absolue http:// ou https://. PunchOut Rocket y dirige le navigateur du client (via le système d’achat pour cXML, directement pour OCI).

Réponses d’erreur

Tout statut non 2xx ou réponse sans sso_url valide fait échouer le PunchOut : le client reçoit une erreur dans son système d’achat. Votre réponse (statut et corps) est enregistrée dans le journal de session PunchOut ; expliquez donc la raison dans le message.

4. Transfert du panier (formulaire à envoi automatique)

Pour un utilisateur PunchOut, le bouton de validation ne doit pas démarrer votre processus de commande : il envoie le panier à PunchOut Rocket. Votre boutique retourne une page HTML qui soumet automatiquement un formulaire masqué, idéalement avec un indicateur de chargement.

• URL : {gateway_base_url}/start-sso-checkout (gateway_base_url de la requête de clonage)
• Méthode : POST, application/x-www-form-urlencoded (envoi classique d’un formulaire du navigateur)
• Pas d’api_key : la session est identifiée par session_token et end_customer_id.

i commence à 0, sans interruption : PunchOut Rocket arrête la lecture au premier indice manquant. Pensez à échapper les valeurs pour HTML.

Exemple de page retournée à la validation de commande

<!doctype html>
<html>
<body>
<p>Sending your cart to your procurement system…</p>
<form id="punchout_repost" method="post" action="https://middleware.example.com/start-sso-checkout">
  <input type="hidden" name="session_token" value="sess-012345"/>
  <input type="hidden" name="end_customer_id" value="2"/>
  <input type="hidden" name="products[0][sku]" value="ABC-001"/>
  <input type="hidden" name="products[0][product_id]" value="19852"/>
  <input type="hidden" name="products[0][description]" value="Example description"/>
  <input type="hidden" name="products[0][quantity]" value="2"/>
  <input type="hidden" name="products[0][price]" value="15.95"/>
  <input type="hidden" name="products[0][currency]" value="EUR"/>
  <input type="hidden" name="products[0][unit_of_measure]" value="EA"/>
  <input type="hidden" name="products[0][manufacturer_name]" value="3M"/>
  <input type="hidden" name="products[0][category_ids]" value="1145,3398"/>
  <input type="hidden" name="products[1][sku]" value="XYZ-002"/>
  <input type="hidden" name="products[1][product_id]" value="19854"/>
  <input type="hidden" name="products[1][description]" value="Another example description"/>
  <input type="hidden" name="products[1][quantity]" value="4"/>
  <input type="hidden" name="products[1][price]" value="10.90"/>
  <input type="hidden" name="products[1][currency]" value="EUR"/>
  <input type="hidden" name="products[1][manufacturer_name]" value="DEWALT"/>
  <input type="hidden" name="products[1][category_ids]" value="2146"/>
</form>
<script>document.getElementById('punchout_repost').submit();</script>
</body>
</html>

PunchOut Rocket envoie alors le panier au système d’achat et termine la session. Une session n’accepte qu’un seul panier :

7. Endpoint d’état des commandes

Chemin par défaut : /api/punchout/order-status. Appelé uniquement pour les clients finaux avec « Send order status updates » activé, pour les commandes créées via la section 6 : chaque heure pendant 60 jours après la commande et immédiatement après une notification (section 8). Nécessite l’option OC & ASN. À partir de la réponse, PunchOut Rocket envoie au système d’achat du client :

• une confirmation de commande (cXML ConfirmationRequest), une seule fois, lorsque la commande est acceptée ou annulée ;
• un avis d’expédition (cXML ShipNoticeRequest) pour chaque nouvelle expédition d’une commande confirmée.

PunchOut Rocket mémorise ses envois : répondez toujours avec l’état actuel de la commande et PunchOut Rocket détermine les nouveautés.

Requête : order_id est celui retourné par votre endpoint de création des commandes

{"api_key": "site-api-key-abc", "order_id": "100045"}

Réponse de succès

HTTP 200

HTTP 200
{
  "status": "success",
  "order_status": "shipped",
  "items": ["5501", "5502"],
  "quantities": [
    {"order_item_id": "5501", "quantity": 2},
    {"order_item_id": "5502", "quantity": 1}
  ],
  "shipments": [
    {
      "id": "SH-1",
      "shipped_at": "2026-11-12T09:30:00+01:00",
      "carrier": "UPS",
      "tracking": "1Z999AA10123456784",
      "items": [{"order_item_id": "5501", "quantity": 2}]
    }
  ]
}

La confirmation est envoyée une seule fois, lorsque la commande devient pour la première fois processing, shipped ou delivered :

• elle accepte toute la commande si chaque ligne du PO y figure intégralement ;
• sinon, elle accepte chaque ligne pour la quantité présente dans la commande et rejette le reste (articles supprimés, quantités réduites). Une quantité supérieure au PO est confirmée à hauteur de celle du PO ;
• s’il ne reste aucune ligne, rien n’est envoyé : utilisez cancelled pour rejeter la commande.

Les modifications ultérieures des articles ne sont pas reconfirmées : modifiez la commande avant de l’accepter.

Signalez une expédition seulement après son départ. Les modifications effectuées après sa notification ne sont pas renvoyées. Si le système d’achat refuse une confirmation ou un avis d’expédition, PunchOut Rocket le renvoie au prochain contrôle et bloque les envois suivants jusqu’à son acceptation.

9. Contrôles avant la mise en production

1. Configurez le site (section 1) et renseignez la même clé API dans votre boutique.
2. Créez un client final et définissez son « E-commerce User to Clone ».
3. Cliquez sur « Update from e-commerce » dans son Category Mapping et associez les catégories ; définissez un Default UNSPSC.
4. Testez un PunchOut avec le formulaire de test cXML du panneau d’administration : create, puis edit avec un panier, puis retournez le panier.
5. Pour les bons de commande (forfait Premium) : envoyez un OrderRequest de test et vérifiez la commande dans votre boutique.
6. Pour les mises à jour d’état (option OC & ASN) : activez « Send order status updates » sur le client final, faites passer la commande de test par vos états et vérifiez que le système du client reçoit la confirmation et les avis d’expédition.

À retenir :

• Les utilisateurs PunchOut ne doivent pas finaliser une commande sur votre boutique : leur panier retourne au système d’achat (section 4) et la commande arrive ensuite via la section 6.
• Les commandes reçues via la section 6 sont déjà approuvées par le système d’achat du client : aucun paiement en ligne n’est nécessaire.

Besoin d’un client de test ou d’une revue de votre implémentation ? Parlez à nos développeurs ou confiez-nous le développement avec Go-Live Assist.