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}

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]	❌ Optional	Material group or internal classification
NEW_ITEM-LEADTIME[n]	❌ Optional	Delivery lead time (in days)
NEW_ITEM-MANUFACTCODE[n]	❌ Optional	Manufacturer code
NEW_ITEM-MANUFACTNAME[n]	❌ Optional	Manufacturer name
NEW_ITEM-MANUFACTMAT[n]	❌ Optional	Manufacturer part number
NEW_ITEM-EXT_PRODUCT_ID[n]	❌ Optional	External product ID (for catalogs)
NEW_ITEM-LONGTEXT[n]	❌ Optional	Long description or free text
NEW_ITEM-IMAGE_URL[n]	❌ Optional	Product image URL
NEW_ITEM-URL[n]	❌ Optional	Product page URL
NEW_ITEM-CONTRACT[n]	❌ Optional	Referenced contract ID
NEW_ITEM-CONTRACT_ITEM[n]	❌ Optional	Contract line number

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.