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]
Obligatoirestring(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]
Optionnelstring(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]
Optionnelstring(9)Retour panier
Groupe de marchandises ou classification. En B2B international, c'est souvent un code UNSPSC à 8 chiffres.
NEW_ITEM-QUANTITY[i]
ObligatoiredecimalRetour panier
Quantité commandée. Décimal positif, point comme séparateur décimal (jamais la virgule).
NEW_ITEM-UNIT[i]
Obligatoireunit(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]
ObligatoiredecimalRetour 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]
OptionnelintegerRetour 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]
Obligatoirecurrency(3)Retour panier
Devise ISO 4217 (EUR, USD, GBP, etc.). 3 lettres majuscules.
NEW_ITEM-DELIVERYDATE[i]
Optionneldate(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]
Optionnelstring(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]
Optionnelstring(40)Retour panier
Référence article chez le fournisseur (SKU, code produit catalogue).
NEW_ITEM-MANUFACTCODE[i]
Optionnelstring(10)Retour panier
Code fabricant (distinct du fournisseur si l'item est revendu).
NEW_ITEM-MANUFACTMAT[i]
Optionnelstring(40)Retour panier
Référence article du fabricant (MPN, Manufacturer Part Number).
NEW_ITEM-CONTRACT[i]
Optionnelstring(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]
Optionnelinteger(5)Retour panier
Poste du contrat cadre. Obligatoire si CONTRACT est rempli.
NEW_ITEM-SERVICE[i]
Optionnelflag(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]
Optionnelinteger(5)Retour panier
Délai de livraison en jours calendaires.
NEW_ITEM-LONGTEXT_1:132[i]
OptionnelstringRetour 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]
Optionnelstring(10)Retour panier
Champ personnalisé 1, libre. Convention spécifique à chaque buyer.
NEW_ITEM-CUST_FIELD2[i]
Optionnelstring(10)Retour panier
Champ personnalisé 2, libre.
NEW_ITEM-CUST_FIELD3[i]
Optionnelstring(10)Retour panier
Champ personnalisé 3, libre.
NEW_ITEM-CUST_FIELD4[i]
Optionnelstring(10)Retour panier
Champ personnalisé 4, libre.
NEW_ITEM-CUST_FIELD5[i]
Optionnelstring(10)Retour panier
Champ personnalisé 5, libre.
NEW_ITEM-ATTACHMENT[i]
Optionnelurl(255)Retour panierOCI 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]
Optionnelstring(50)Retour panierOCI 5.0
Titre affichable de la pièce jointe (sinon le nom de fichier extrait de ATTACHMENT est utilisé).
NEW_ITEM-ATTACHMENT_PURPOSE[i]
Optionnelenum(20)Retour panierOCI 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]
Optionnelstring(40)Retour panierOCI 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]
Optionnelenum(20)Retour panierOCI 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]
Optionnelstring(40)Retour panierOCI 5.0
Identifiant de catégorie externe (UNSPSC, eCl@ss, etc.). Complète MATGROUP.
NEW_ITEM-EXT_CATEGORY[i]
Optionnelstring(60)Retour panierOCI 5.0
Libellé de catégorie externe associé à EXT_CATEGORY_ID.
USERNAME
Obligatoirestring(40)Setup
Identifiant de session pour authentifier le buyer auprès du catalogue supplier. Ne pas confondre avec un login utilisateur.
PASSWORD
Obligatoirestring(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
Obligatoireurl(255)Setup
URL absolue à laquelle le catalogue supplier POSTera le panier de retour. HTTPS très fortement recommandé.
~OkCode
Optionnelenum(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
Optionnelenum(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
Optionnelenum(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
Optionnelstring(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
Optionnelstring(20)SetupOCI 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.

Questions fréquentes

Qu'est-ce qu'un champ OCI ?

Un champ OCI est un paramètre HTTP form-urlencoded utilisé dans le protocole SAP Open Catalog Interface. Les champs de retour panier sont préfixés NEW_ITEM- et indexés par ligne (NEW_ITEM-DESCRIPTION[1], NEW_ITEM-DESCRIPTION[2], etc.). Les paramètres de setup request sont globaux et non indexés (USERNAME, PASSWORD, HOOK_URL, ~OkCode, ~Target, etc.).

Quels champs sont obligatoires en cart return OCI ?

Sur chaque ligne du panier, cinq champs sont obligatoires : NEW_ITEM-DESCRIPTION (libellé, max 40 caractères), NEW_ITEM-QUANTITY (décimal positif), NEW_ITEM-UNIT (code unité), NEW_ITEM-PRICE (décimal, point comme séparateur) et NEW_ITEM-CURRENCY (code ISO 4217 sur 3 lettres).

Quels paramètres sont obligatoires en setup request OCI ?

Trois paramètres minimum : USERNAME (identifiant de session), PASSWORD (mot de passe ou token de session, à envoyer en POST) et HOOK_URL (URL absolue de retour panier, HTTPS recommandé). Les paramètres ~OkCode, ~Target, ~Caller et LANGU sont optionnels mais quasi systématiques en pratique.

Quels champs sont propres à OCI 5.0 ?

OCI 5.0 a ajouté les champs liés aux pièces jointes (NEW_ITEM-ATTACHMENT, ATTACHMENT_TITLE, ATTACHMENT_PURPOSE), aux références produit externes (NEW_ITEM-EXT_PRODUCT_ID, EXT_SCHEMA_TYPE) et aux catégories externes (EXT_CATEGORY_ID, EXT_CATEGORY). Côté setup, RETURNTARGET a été introduit en 5.0. L'adoption reste limitée aux grands industriels sur S/4HANA récents.

Quelle est la différence entre PRICE et PRICEUNIT ?

PRICE est le prix unitaire pour PRICEUNIT unités. Si PRICEUNIT n'est pas envoyé, SAP utilise la valeur par défaut 1 (prix par unité). Si PRICEUNIT=1000 et PRICE=12.50, cela signifie 12.50 EUR pour 1000 unités. C'est la source numéro un d'erreurs prix x100 / x1000 en intégration OCI quand l'acheteur ne mappe pas PRICEUNIT.

Qu'est-ce que sapevent:post dans le retour panier OCI (HOOK_URL) ?

Dans les scénarios SAP GUI historiques (ITS / WebGUI, etc.), le HOOK_URL transmis par SAP peut contenir une pseudo-URL sapevent: : le formulaire de retour panier poste alors vers sapevent:post et le navigateur embarqué convertit le submit en événement SAP qui restitue les champs NEW_ITEM-* à la transaction SAP. Dans les scénarios web (SRM, S/4HANA, etc.), HOOK_URL est une URL HTTPS standard et le retour panier est un simple POST de formulaire vers cette URL.