Aller au contenu
Gatebold

Référence OCI

Tous les champs OCI 4.0 et 5.0 en un coup d'œil.

38 champs documentés : retour panier (NEW_ITEM-*) et setup request (USERNAME, HOOK_URL, ~OkCode, etc.). Format, longueur, version, descriptions FR + EN.

Pour tester un payload OCI réel contre ces règles, utilisez le validateur OCI ou parcourez la bibliothèque d'exemples.

Référence des champs OCI

Tous les champs OCI 4.0 et 5.0 reconnus par le validateur, avec leur format attendu, leur longueur maximale et leur description. 38 champs au total.

OCI 4.0 + 5.0
Filtrer

Notation : [i] = champ répété par ligne de panier (i = numéro de ligne, à partir de 1).

  • NEW_ITEM-DESCRIPTION[i]
    Obligatoire string(40) Retour panier

    Libellé court de l'article tel qu'il apparaîtra dans le panier acheteur. Tronqué à 40 caractères côté SAP.

  • NEW_ITEM-MATNR[i]
    Optionnel string(40) Retour panier

    Référence article du fournisseur dans le système acheteur. Utilisé si l'acheteur tient un référentiel matières.

  • NEW_ITEM-MATGROUP[i]
    Optionnel string(9) Retour panier

    Groupe de marchandises ou classification. En B2B international, c'est souvent un code UNSPSC à 8 chiffres.

  • NEW_ITEM-QUANTITY[i]
    Obligatoire decimal Retour panier

    Quantité commandée. Décimal positif, point comme séparateur décimal (jamais la virgule).

  • NEW_ITEM-UNIT[i]
    Obligatoire unit(3) Retour panier

    Unité de mesure. Spec OCI = code ISO/UN-ECE (PCE, KGM, MTR, etc.). Beaucoup d'installations SAP attendent les codes internes T006 (ST, KG, M, etc.) - le validateur signale les deux cas.

  • NEW_ITEM-PRICE[i]
    Obligatoire decimal Retour panier

    Prix unitaire (pour PRICEUNIT unités, par défaut 1). Décimal, point comme séparateur. Toujours valider la cohérence PRICE / PRICEUNIT / QUANTITY.

  • NEW_ITEM-PRICEUNIT[i]
    Optionnel integer Retour panier

    Quantité à laquelle s'applique PRICE. Si PRICE=12.50 et PRICEUNIT=1000, le prix est de 12.50 pour 1000 unités. Absence = 1. Source numéro 1 d'erreurs de prix x100 / x1000 en prod.

  • NEW_ITEM-CURRENCY[i]
    Obligatoire currency(3) Retour panier

    Devise ISO 4217 (EUR, USD, GBP, etc.). 3 lettres majuscules.

  • NEW_ITEM-DELIVERYDATE[i]
    Optionnel date(10) Retour panier

    Date de livraison souhaitée au format ISO 8601 (YYYY-MM-DD). Très utilisé en MRO et achats indirects.

  • NEW_ITEM-VENDOR[i]
    Optionnel string(10) Retour panier

    Numéro de fournisseur dans le système acheteur. Doit correspondre au fournisseur préenregistré côté SAP, sinon l'item est rejeté.

  • NEW_ITEM-VENDORMAT[i]
    Optionnel string(40) Retour panier

    Référence article chez le fournisseur (SKU, code produit catalogue).

  • NEW_ITEM-MANUFACTCODE[i]
    Optionnel string(10) Retour panier

    Code fabricant (distinct du fournisseur si l'item est revendu).

  • NEW_ITEM-MANUFACTMAT[i]
    Optionnel string(40) Retour panier

    Référence article du fabricant (MPN, Manufacturer Part Number).

  • NEW_ITEM-CONTRACT[i]
    Optionnel string(10) Retour panier

    Numéro de contrat cadre côté acheteur, si l'article est rattaché à un contrat négocié.

  • NEW_ITEM-CONTRACT_ITEM[i]
    Optionnel integer(5) Retour panier

    Poste du contrat cadre. Obligatoire si CONTRACT est rempli.

  • NEW_ITEM-SERVICE[i]
    Optionnel flag(1) Retour panier

    Drapeau service. 'X' = ligne de prestation de service (pas de marchandise physique), vide = bien physique.

    Valeurs admises : X

  • NEW_ITEM-LEADTIME[i]
    Optionnel integer(5) Retour panier

    Délai de livraison en jours calendaires.

  • NEW_ITEM-LONGTEXT_1:132[i]
    Optionnel string Retour panier

    Texte descriptif long, à utiliser quand DESCRIPTION (40 car.) est trop court. Syntaxe particulière : NEW_ITEM-LONGTEXT_i:132[] où i est l'index de ligne et 132 la largeur max d'une 'ligne' de texte.

  • NEW_ITEM-CUST_FIELD1[i]
    Optionnel string(10) Retour panier

    Champ personnalisé 1, libre. Convention spécifique à chaque buyer.

  • NEW_ITEM-CUST_FIELD2[i]
    Optionnel string(10) Retour panier

    Champ personnalisé 2, libre.

  • NEW_ITEM-CUST_FIELD3[i]
    Optionnel string(10) Retour panier

    Champ personnalisé 3, libre.

  • NEW_ITEM-CUST_FIELD4[i]
    Optionnel string(10) Retour panier

    Champ personnalisé 4, libre.

  • NEW_ITEM-CUST_FIELD5[i]
    Optionnel string(10) Retour panier

    Champ personnalisé 5, libre.

  • NEW_ITEM-ATTACHMENT[i]
    Optionnel url(255) Retour panier OCI 5.0

    URL d'une pièce jointe (fiche technique, plan, photo). HTTPS recommandé, accessible publiquement ou via le tunnel d'authentification de l'acheteur.

  • NEW_ITEM-ATTACHMENT_TITLE[i]
    Optionnel string(50) Retour panier OCI 5.0

    Titre affichable de la pièce jointe (sinon le nom de fichier extrait de ATTACHMENT est utilisé).

  • NEW_ITEM-ATTACHMENT_PURPOSE[i]
    Optionnel enum(20) Retour panier OCI 5.0

    Catégorie de la pièce jointe. Valeurs typiques : DATASHEET, DRAWING, PHOTO, CERTIFICATE, OTHER, etc.

    Valeurs admises : DATASHEET, DRAWING, PHOTO, CERTIFICATE, OTHER

  • NEW_ITEM-EXT_PRODUCT_ID[i]
    Optionnel string(40) Retour panier OCI 5.0

    Identifiant produit externe (GTIN, EAN, etc.). À utiliser avec EXT_SCHEMA_TYPE pour préciser le référentiel.

  • NEW_ITEM-EXT_SCHEMA_TYPE[i]
    Optionnel enum(20) Retour panier OCI 5.0

    Référentiel de EXT_PRODUCT_ID. Valeurs : GTIN, EAN, UPC, UNSPSC, ECLASS, OTHER.

    Valeurs admises : GTIN, EAN, UPC, UNSPSC, ECLASS, OTHER

  • NEW_ITEM-EXT_CATEGORY_ID[i]
    Optionnel string(40) Retour panier OCI 5.0

    Identifiant de catégorie externe (UNSPSC, eCl@ss, etc.). Complète MATGROUP.

  • NEW_ITEM-EXT_CATEGORY[i]
    Optionnel string(60) Retour panier OCI 5.0

    Libellé de catégorie externe associé à EXT_CATEGORY_ID.

  • USERNAME
    Obligatoire string(40) Setup

    Identifiant de session pour authentifier le buyer auprès du catalogue supplier. Ne pas confondre avec un login utilisateur.

  • PASSWORD
    Obligatoire string(40) Setup

    Mot de passe ou token de session. À envoyer en POST (et non en GET) pour ne pas exposer le secret dans les logs serveur.

  • HOOK_URL
    Obligatoire url(255) Setup

    URL absolue à laquelle le catalogue supplier POSTera le panier de retour. HTTPS très fortement recommandé.

  • ~OkCode
    Optionnel enum(4) Setup

    Action SAP déclenchée au retour. ADDI = ajout au panier en cours (standard), CRTE = création d'une demande d'achat directe. Choisir ADDI sauf cas spécifique côté SRM.

    Valeurs admises : ADDI, CRTE

  • ~Target
    Optionnel enum(10) Setup

    Cible du formulaire de retour. _top = échappe toutes les frames (recommandé), _parent = remonte d'une frame, _self = reste dans la frame courante (provoque souvent des bugs 'cart never returns').

    Valeurs admises : _top, _parent, _self

  • ~Caller
    Optionnel enum(4) Setup

    Module appelant côté SAP. CTLG = catalogue (par défaut), SC = Shopping Cart, PO = Purchase Order. N'affecte que l'affichage côté ERP.

    Valeurs admises : CTLG, SC, PO

  • LANGU
    Optionnel string(2) Setup

    Code langue 1 ou 2 lettres (E, D, F, EN, DE, FR, etc.). Permet au catalogue d'afficher dans la bonne langue.

  • RETURNTARGET
    Optionnel string(20) Setup OCI 5.0

    Indique au supplier la fenêtre cible du retour quand HOOK_URL est servie dans une nouvelle fenêtre. Rarement utilisé.

Comment lire cette référence

OCI (SAP Open Catalog Interface) n'est pas du XML : c'est un protocole basé sur des paramètres HTTP form-urlencoded. Chaque payload de retour panier contient des paires NEW_ITEM-CHAMP[i]=valeur, où i est l'index de ligne (à partir de 1). Les paramètres de setup request sont globaux et préfixés différemment (parfois par ~ pour les paramètres SAP réservés).

Pour chaque champ, la table indique :

  • Nom exact (sensible à la casse côté SAP), suivi de [i] si le champ est répété par ligne.
  • Statut obligatoire ou optionnel selon la spec OCI 4.0.
  • Type et longueur max : SAP tronque silencieusement les valeurs trop longues.
  • Mode : retour panier (cart return) ou setup request.
  • Version OCI : la plupart des champs existent depuis 4.0, certains ont été ajoutés en 5.0 (attachments, références produit externes, etc.).
  • Description bilingue avec contexte d'usage et pièges connus.

Les champs à connaître absolument

  • NEW_ITEM-PRICEUNIT - la source numéro un de bugs prix x1000 en production. À toujours mapper côté acheteur.
  • NEW_ITEM-MATGROUP - groupe de marchandises, souvent un code UNSPSC à 8 chiffres. Voir le référentiel UNSPSC.
  • NEW_ITEM-UNIT - codes UN/ECE selon la spec (PCE, KGM, MTR), mais la plupart des SAP attendent des codes T006 internes (ST, KG, M). Bien coordonner le mapping unité avec le buyer.
  • HOOK_URL - URL absolue où le supplier POST le panier. Toujours en HTTPS dans les scénarios web, syntaxe stricte, jamais en mixed-content depuis un catalogue HTTPS. Dans les scénarios SAP GUI historiques (ITS / WebGUI, etc.), HOOK_URL peut au contraire contenir une pseudo-URL sapevent: : le formulaire de retour panier poste alors vers sapevent:post et le navigateur embarqué transforme le submit en événement SAP qui restitue les champs NEW_ITEM-* à la transaction.
  • ~Target - cible du formulaire de retour panier auto-submit. Trois valeurs possibles :
    • _top (recommandé) : casse toutes les frames et POST dans la fenêtre browser top-niveau, donc le SRM intercepte le panier normalement.
    • _self : POST dans la frame courante. Si le catalogue tourne en iframe (cas standard SAP SRM), le retour reste piégé dans l'iframe et le SRM ne voit jamais rien → HOOK_URL n'est jamais déclenché, le panier disparaît.
    • _parent : remonte d'une seule frame. Risqué si plusieurs iframes imbriquées (reverse proxy + SRM Portal).

OCI 4.0 ou OCI 5.0 ?

OCI 4.0 reste le standard de fait sur la grande majorité du parc installé. OCI 5.0 a ajouté les pièces jointes, les références produit externes (GTIN, EAN, UNSPSC, eCl@ss, etc.) et une hiérarchie service plus riche. Démarrer en 4.0, ajouter les champs 5.0 uniquement si le buyer le demande explicitement. Voir l'article complet sur OCI.

Pour aller plus loin

  • Validateur OCI - tester un payload OCI (setup request ou cart return) contre toutes les règles documentées ici, en 100% navigateur.
  • Exemples de payloads OCI - 7 exemples curés (minimal, complet, PRICEUNIT trap, OCI 5.0 attachments, etc.) prêts à copier ou tester directement dans le validateur.
  • Validateur cXML - le pendant pour le protocole cXML, validation contre le DTD officiel 1.2.070.
  • cXML vs OCI - comparaison protocolaire complète.
  • Codes UNSPSC - le référentiel produit/service pour le champ NEW_ITEM-MATGROUP.