Product Documentation
Product Documentation
This is the OCI (SAP Open Catalog Interface) counterpart to the cXML PunchOut documentation. It covers the endpoints a customer's procurement system needs, how the Punchout customer is set up in Kodaris, the connection parameters to hand the customer, and test payloads to validate the flow.
cXML vs OCI in one line: cXML is a server-to-server XML POST. OCI is browser-driven — SAP redirects the shopper's browser to Kodaris with the credentials + a HOOK_URL as query parameters. After authentication the two protocols share the same login/cart flow; they differ only at the entry point and the cart-return format.
There are two groups of OCI endpoints. Only the entry/setup URL is configured on the customer's side — it's the public URL SAP redirects the browser to. The remaining endpoints are customer-session endpoints the Kodaris storefront calls internally after the buyer is logged in; they require an authenticated customer session (not the SAP entry credentials).
| Purpose | Method | URL |
| OCI Setup / Entry (configure this in SAP as the catalog/punchout URL) | GET | https://[your-kodaris-store-url]/api/user/oci/punchOut/setup |
The entry endpoint authenticates the buyer and issues a browser redirect (HTTP 302) to the Kodaris storefront login, landing the shopper in the catalog. When they finish shopping, the storefront posts the cart back to the HOOK_URL SAP supplied, as OCI NEW_ITEM-* form fields.
These are called by the storefront during the shopping session and require an authenticated customer session. Listed for completeness; the customer's procurement system does not call them directly.
| Purpose | Method | URL |
| Generate OCI cart data (NEW_ITEM-* as JSON) | GET | /api/account/oci/punchOut/cart |
| Cart transmission page (auto-submits the cart to HOOK_URL, then clears it) | GET | /api/account/oci/punchOut/cartTransmission |
| Clear the current OCI cart (set order status + empty it) | POST | /api/account/oci/punchOut/clearCart |
| Whether the current session is an OCI Punchout user | GET | /api/account/oci/punchOut/userStatus |
SAP appends these as query parameters on the Setup URL. Parameter names are the OCI standard.
| Parameter | Required | Description |
| HOOK_URL | Yes | The cart return address. SAP supplies it; Kodaris stores it verbatim and posts the finished cart back to it. |
| username | Yes | The buyer's OCI username. Maps to the Kodaris Punchout customer's username (the Sender Identity in cXML terms). |
| password | Yes | The buyer's OCI password. Maps to the Punchout customer's shared secret / PUNCHOUT API Key. |
| returntarget | No | Browser frame/window the cart-return form targets. Defaults to _top. |
| OCI_VERSION | No | OCI protocol version, passed through if provided. |
Authentication: identical mechanism to cXML — username + password must match a Kodaris Punchout integration customer's username + shared secret. We do not validate any other values. If authentication fails, the endpoint returns 401 Unauthorized; a missing HOOK_URL returns 400 Bad Request.
The Punchout customer is created exactly the same way as for cXML. In the Operations Portal:
This is the same customer + key used for cXML — a single Punchout customer works for both protocols. The username you set here is the OCI username, and the PUNCHOUT API Key is the OCI password.
For full screenshots of the customer-creation steps, see the existing "Operations CRM — Punchout Customer Creation" documentation — the steps are identical for OCI.
Connection parameters for the customer's OCI configuration:
The customer's procurement system may ask for the values below. We do not validate anything other than the username (Sender Identity) and password (shared secret).
| Field | Example | Description |
| OCI Catalog / Setup URL | https://[your-kodaris-url]/api/user/oci/punchOut/setup | The entry endpoint SAP redirects to |
| username | punchout-114729@yourdomain.com | Set up in Kodaris above (Punchout customer username) |
| password | xxxx-xxxx-xxx | Set up in Kodaris above (PUNCHOUT API Key) |
| HOOK_URL | (SAP supplies) | Cart return address; sent by SAP at runtime, not configured by you |
| returntarget | _top | Optional; defaults to _top |
| OCI_VERSION | 4.0 | Optional |
Because OCI entry is a browser GET, a test is just a URL you can paste into a browser (or curl). Replace the host, username, password, and HOOK_URL with real values.
https://[your-kodaris-url]/api/user/oci/punchOut/setup?HOOK_URL=https%3A%2F%2Fbuyer.example.com%2Foci%2Freturn&username=punchout-114729@yourdomain.com&password=xxxx-xxxx-xxx
Expected: HTTP 302 redirect to the Kodaris storefront login; following it lands you in the catalog as the Punchout buyer.
https://[your-kodaris-url]/api/user/oci/punchOut/setup?HOOK_URL=https%3A%2F%2Fbuyer.example.com%2Foci%2Freturn&username=punchout-114729@yourdomain.com&password=xxxx-xxxx-xxx&returntarget=_top&OCI_VERSION=4.0
Note on HOOK_URL encoding: it must be URL-encoded when placed in the query string (e.g. https:// → https%3A%2F%2F). Kodaris stores the decoded value verbatim.
After the buyer checks out, the storefront auto-submits an HTML form POST to the HOOK_URL with hidden NEW_ITEM-* fields, one set per line item. Example fields for a single-line cart:
NEW_ITEM-DESCRIPTION[1]=Widget, 1/2 inch
NEW_ITEM-VENDORMAT[1]=WID-500
NEW_ITEM-QUANTITY[1]=2
NEW_ITEM-UNIT[1]=EA
NEW_ITEM-PRICE[1]=12.50
NEW_ITEM-PRICEUNIT[1]=1
NEW_ITEM-CURRENCY[1]=USD
NEW_ITEM-EXT_PRODUCT_ID[1]=WID-500
NEW_ITEM-MANUFACTMAT[1]=MFG-12345
| Situation | Response |
| Missing HOOK_URL | 400 Bad Request — "Missing HOOK_URL" |
| Invalid username / password | 401 Unauthorized — "Unauthorized: invalid OCI credentials" |
| Any other processing error | 500 |
Every OCI entry and cart return is logged to S3 under punchOut/{date}/ (same location as cXML logs), viewable in Operations Portal → Development → Punch out Orders:
If a setup fails, check the OciSetupRequest log first to verify the credentials and HOOK_URL that came in.