Other shop systems | Create OCI and cXML PunchOut Catalogues

Do you operate your e-commerce platform as an in-house development? This document supports you in implementing the necessary interfaces to our PunchOut gateway.

The initial creation and subsequent updating of customers is carried out by you via the PunchCommerce web interface. The following parameters are maintained by the supplier for each customer:

Jump-in address Url of the online shop to which the customer is forwarded after successful authentication

Customer identification (uID) Value that is transferred to the entry address to identify the customer

Calling up your online shop

After successful authentication of the customer on our gateway, the customer is forwarded to the entry address defined in the customer configuration.

PunchCommerce currently supports the "classic" PunchOut and the PunchOut in an iFrame within the calling e-procurement or ERP system and the PunchOut in a separate browser window.

The entry address is extended by the parameters sID (session identifier) and uID (customer identifier) so that the final URL is structured according to the following scheme:

https://{hostname}.{domain}.{tld}/punchcommerce/authenticate?sID={UUID}&uID= {customer.identifier}

It must be ensured that all headers that prevent embedding as an iFrame and access to cookies from the main frame during the PunchOut session are temporarily removed when the user is logged in.

The user in your system must be extended so that the uID can be maintained at the customer. The sID is generated by us for each PunchOut session and corresponds to a UUID.

As this is typically a service user and several people use the same service user as part of the PunchOut, it must be ensured that different shopping baskets can be used in parallel in different sessions of the same service user.

The shopping basket must be empty at the start of a PunchOut session.

General requirements during the PunchOut session

During the PunchOut session, the SameSite attribute must be set to the value none for all cookies relevant to the session and the Secure attribute must be set to 1
The X-Frame-Options header must be removed during the PunchOut session if it is present
The checkout is replaced by the overview of the shopping basket for the PunchOut and the forwarding to PunchCommerce
The labelling of the relevant user actions "Checkout" is replaced accordingly by a label "PunchOut" or "Back to e-procurement system"

Return of the shopping basket

After the customer has finally filled their shopping basket, the shopping basket must be sent back to our gateway as a JSON object together with the session identifier (sID). Surcharges or discounts are transferred to our gateway as a separate shopping basket item - this also applies to shipping costs.

{
    "basket":[
    {
      "product_ordernumber": "23762", "product_name": "Parchment paper", "quantity": 1,
      "item_price": 2.623,
      "price": 2.623,
      "price_net": 2.2042016806723, "tax_rate": 19,
      "product": {
      "id": "21312432343",
      "ordernumber": "23762",
      "brand": "Netzdirektion",
      "brand_ordernumber": "67906",
      "title": "Parchment paper",
      "category": "Test category",
      "description": "1/8 sheet white",
      "description_long": "67906 Parchment paper 1/8 sheet white", "image_url": "",
      "price": 2.623,
      "tax_rate": 19,
      "purchase_unit": 12.5, "reference_unit": 1,
      "unit": "kg",
      "unit_name": "kg", "packaging_unit": "carton", "weight": 0,
      "shipping_time": 8,
      "classification_type": "ECLASS",
      "classification": "90909090",
      "custom_field1": "0.19",
      "custom_field2": "BX",
      ...
      "custom_field10": null
    }
    ]
}

An http-POST request to the following address is to be executed here. The request body should contain the shopping basket analogue to the following structure.

https://www.punchcommerce.de/gateway/v3/return?sID={UUID}

PunchCommerce applies the field mapping defined for the customer to the shopping basket and transmits the shopping basket to the calling e-procurement system via the respective PunchOut protocol. Details can be found in the current Swagger documentation.

Links