PunchOut OCI Integration

DJUST supports PunchOut workflows using the OCI protocol, in addition to the existing cXML support. This allows B2B buyers using SAP or other OCI-compatible eProcurement systems to connect seamlessly to a DJUST store, browse products, and return their selection as a structured cart.

🔐 Step 1 – PunchOut Session Initialization

The first step in an OCI PunchOut flow is to allow the buyer to “punch out” from their eProcurement system into the supplier’s storefront on DJUST.

The process follows this sequence:

sequenceDiagram
    participant EProc as 🛒 Buyer (eProcurement)
    participant PunchOut as 🧩 PunchOut Module (Djust)
    participant Backend as 🛠️ Djust Backend
    participant Frontend as 👤 Supplier Catalog (Storefront)

    %% Etapes principales du parcours PunchOut OCI

    EProc->>PunchOut: POST/GET PunchOut Request (OCI)<br>(username, password, operation=create, returnURL, EDI...)
    PunchOut->>Backend: Verifies OCI credentials
    Backend-->>PunchOut: OK / Token / Session
    PunchOut->>Frontend: Redirection to the supplier's catalog (with session)
    Frontend->>Backend: Get customer user information (auth via session)
    Backend-->>Frontend: Customer user data, personnalized prices, etc.
    Frontend-->>Frontend: PunchOut catalog displayed

To establish this connection, the eProcurement solution must perform an authentication call to the following endpoints:

ADM-PUNCHOUT-100 - POST /punchout/oci/setup/{tenantConfigurationKey}

Or

ADM-PUNCHOUT-501 - GET /punchout/oci/setup/{tenantConfigurationKey}

The tenantConfigurationKey is a secure value provided by DJUST and managed by your Customer Success Manager.

• ✅ On success, the user is redirected to the appropriate DJUST storefront.
• ❌ On failure, the user is redirected to an error page.

🛒 Step 2 – Cart Generation & Return to ERP

Once the user has landed on the DJUST catalog, browsed products, and added items to their cart, the session must return to the eProcurement system with the structured cart data.

This step is illustrated below:

sequenceDiagram
    participant EProc as 🛒 Buyer (eProcurement)
    participant PunchOut as 🧩 PunchOut Module (Djust)
    participant Backend as 🛠️ Djust Backend
    participant Frontend as 👤 Supplier Catalog (Storefront)

    %% The user browses the site
    Note right of Frontend: The user selects products

    Frontend->>Backend: Add products to cart
    Backend-->>Frontend: Cart updated

    %% End of flow – return to eProc
    Frontend->>PunchOut: Generate OCI form<br>with formatted cart
    PunchOut->>EProc: POST OCI return (HOOK_URL)<br>with encoded cart

    Note right of EProc: The cart is integrated into the purchase order

To retrieve the cart in OCI format, the frontend must call the following route:

ADM-PUNCHOUT-500 - GET /punchout/oci/{tenantConfigurationKey}/commercial-orders/{commercialOrderId}

This route returns the cart contents as a key-value JSON object conforming to the OCI standard:

{
  "NEW_ITEM-DESCRIPTION[0]": "Pen",
  "NEW_ITEM-PRICE[0]": "2.50",
  "NEW_ITEM-QUANTITY[0]": "10",
  "NEW_ITEM-UNIT[0]": "EA",
  "NEW_ITEM-CURRENCY[0]": "EUR",
  "NEW_ITEM-DESCRIPTION[1]": "Highlighter Set",
  "NEW_ITEM-PRICE[1]": "12.00",
  "NEW_ITEM-QUANTITY[1]": "2",
  "NEW_ITEM-UNIT[1]": "BX",
  "NEW_ITEM-CURRENCY[1]": "EUR"
}

These fields must then be used by the frontend to generate a form POST directed to the buyer’s eProcurement platform (usually via the HOOK_URL parameter passed at PunchOut session start).

🧩 Notes

• This integration supports SAP OCI standard fields, and can be extended to include customer-specific mappings if needed.

• Standard supported fields are:

  Field	Required	Description
  NEW_ITEM-DESCRIPTION[n]	✅ Yes	Product description
  NEW_ITEM-QUANTITY[n]	✅ Yes	Quantity ordered
  NEW_ITEM-UNIT[n]	✅ Yes	Unit of measure (e.g., EA, PCE)
  NEW_ITEM-PRICE[n]	✅ Yes	Unit price
  NEW_ITEM-CURRENCY[n]	✅ Yes	Currency (e.g., EUR, USD)
  NEW_ITEM-VENDORMAT[n]	✅ Yes	Supplier item ID (SKU, internal code)
  NEW_ITEM-MATGROUP[n]	❌	Material group or internal classification
  NEW_ITEM-LEADTIME[n]	❌	Delivery lead time (in days)
  NEW_ITEM-MANUFACTCODE[n]	❌	Manufacturer code
  NEW_ITEM-MANUFACTNAME[n]	❌	Manufacturer name
  NEW_ITEM-MANUFACTMAT[n]	❌	Manufacturer part number
  NEW_ITEM-EXT_PRODUCT_ID[n]	❌	External product ID (for catalogs)
  NEW_ITEM-LONGTEXT[n]	❌	Long description or free text
  NEW_ITEM-IMAGE_URL[n]	❌	Product image URL
  NEW_ITEM-URL[n]	❌	Product page URL
  NEW_ITEM-CONTRACT[n]	❌	Referenced contract ID
  NEW_ITEM-CONTRACT_ITEM[n]	❌	Contract line number
  NEW_ITEM-PRICEUNIT[n]	❌	Number of units to which the price indicated in NEW_ITEM-PRICE[n] applies
  NEW_ITEM_TAX[n]	❌	Tax amount per line

• Non standard supported fields are:

  Field	Required	Description
  NEW_ITEM-SHIPPING_TAX[n]	❌	Amount of taxes on delivery charges
  NEW_ITEM-CATEGORYID[n]	❌	Classification category (often via UNSPSC)
  NEW_ITEM-SUPPLIER_ID[n]	❌	Supplier ID

  
  

• Redirection URLs and form behavior should be handled securely on the frontend, respecting the ERP’s expectations.

• Error handling follows Djust PunchOut error management for OCI-compliant fallbacks.