Processing of cXML orders (e.g. from SAP Ariba®)

Introduction

With the revised order module of PunchCommerce, you can securely receive incoming orders from different systems - especially in cXML format - and seamlessly forward them to your target systems.

Orders are automatically confirmed as received upon receipt. You then have two options:

1. Request via REST API - you integrate the module flexibly into your own systems. 2) Automatic forwarding - e.g. to Shopware 6 or other shop systems.

This significantly reduces manual effort, transmission errors are avoided and collaboration with your customers' e-procurement systems becomes more efficient.

Please note: The functions for defining your own data formats and for operating multiple order profiles are currently only available to selected customers as part of our Enterprise contracts.

Creation of an order profile

Order profiles are the core of our order module. Here you have the option of defining your own data model and making it available via a REST API. An order profile can be assigned to one or more customers.

1. switch to the Order profiles area and click on Create new order profile. 2) Assign a name to your profile.
2. upload a cXML file of the type OrderRequest.
3. PunchCommerce generates a proposal for the data model based on the cXML data model, which you can customise if required.

Transmission of orders from third party systems

Procurement systems such as Ariba® or Coupa can be configured so that new orders from your customers are automatically transmitted as cXML-OrderRequest to the following address:

https://<instance>.enterprise.punchcommerce.de/api/v1/orders/cxml

The endpoint expects a cXML-OrderRequest document according to the specification in chapter 7 of the cXML-Reference Guide.

Important: Orders can only be received for customers to whom you have assigned an order profile. Orders for unknown customers or customers without a profile are automatically rejected and are not available for processing via our API.

Example document

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML xml:lang="en-US" payloadID="93369535150910.10.57.136" timestamp="2000-08-03T08:49:11+07:00">
  <header>
    ...
  </header>
  <Request>
    <OrderRequest>
      <OrderRequestHeader orderID="DO102880" orderDate="2012-08-03T08:49:09+07:00" type="new">
        ...
      </OrderRequestHeader>
      <ItemOut quantity="2" lineNumber="1">
        ...
      </ItemOut>
    </OrderRequest>
  </OrderRequest>
</cXML>

Example response

If no error occurs when processing the order, our system responds with the following response as confirmation of receipt. No commercial obligation arises in this step:

<cXML payloadID="9949494" xml:lang="en" timestamp="1999-03-12T18:39:09-08:00">
  <Response>
    <status code="200" text="OK"/>
  </response>
</cXML>

Access to the orders via our REST API

Individual access data in the form of a token and a URL for our REST API are generated for each order profile.

List of all orders in a profile

GET {{punchcommerce_host}}/api/v1/profile/{{profile_id}}

Response:

{
  "data": {
    "id": "4a152855-1a26-4059-a637-4d56cc151d9e",
    "name": "adsd",
    "customers": [
      {
        "uuid": "69f14942-178d-4d57-b6d5-fdd9d4aee407",
        "name": "Mraz Inc"
      }
    ],
    "orders": [
      {
        "id": "cb074373-60d9-4c1b-9453-988602da457e",
        "customer_id": "69f14942-178d-4d57-b6d5-fdd9d4aee407",
        "customer": "Mraz Inc",
        "created_at": "2022-10-03T13:21:16.000000Z",
        "link": "https://punchcommerce.local/api/v1/profile/4a152855-1a26-4059-a637-4d56cc151d9e/order/cb074373-60d9-4c1b-9453-988602da457e"
      },
      ...
    ]
  }
}

Details of an order

The answer depends on the data model that you have configured for the corresponding order profile in our system.

GET {{punchcommerce_host}}/api/v1/profile/{{profile_id}}/order/{{order_id}}

Example response:

{
  "data": {
    "meta": {
      "request_id": "1637737323553.569506334.000002897@IrwnYChEL2oZa48FesaJ62+R18I=",
      "cxml_version": "1.2.044",
      "language": "en-US"
    },
    "order": {
      "total": "17",
      "currency": "EUR",
      "date": "2021-11-23T23:01:59-08:00",
      "reference": "EP686328",
      "version": 1,
      "billing": {
        "company": "FOOBAR GMBH - RECHNUNGSPRUEFUNG",
        "street": "Walter-Flex-Str. 27",
        "zip": "24000",
        "city": "Hamburg",
        "country": "Germany"
      },
      "shipping": {
        "company": "FOOBAR GMBH",
        "street": "Walter-Flex-Str. 27",
        "zip": "65428",
        "city": "Rüsselsheim",
        "country": "Germany"
      },
      "items": [
        {
          "index": 1,
          "ordernumber": "FOOBAR_VK-deutsch_up",
          "quantity": 100,
          "name": "FOOBAR Business Card (German)",
          "unit_price": "0.17",
          "unit": "EA"
        }
      ]
    }
  }
}

Forwarding of orders

In addition to pure retrieval via the REST API, orders can also be automatically forwarded to shop systems. We currently support Shopware 6 in particular. Further systems are in preparation.

Functionality

1. receipt of an order (e.g. cXML).
2. PunchCommerce transforms the data into an internal standard format.
3. configured target system (Shopware 6) is supplied via the Admin API. 4) PunchCommerce takes into account fallbacks for payment methods, shipping methods, currencies and tax rates.

Configuration

• Select the target system in the order profile (e.g. Shopware).
• Store access data: URL, client ID (access key), client secret.
• Test connection (PunchCommerce checks authentication and loads payment methods, shipping methods, currencies, tax rates).
• Configure default values if they cannot be clearly derived from the order.

Result

• Order appears directly in the Shopware backend with the prefix PUNCH- in the order number.
• Missing products can be ignored or treated as errors, depending on the setting.
• Process is transparent: success and errors are logged in the PunchCommerce interface.

Note: IDs for payment methods or shipping methods that have been deleted in Shopware can trigger errors. Please retest and save the connection in PunchCommerce after making changes in Shopware.

Operation & Quality Assurance

• Regularly check the success messages in the PunchCommerce interface.
• Keep master data (products, currencies, taxes) up to date.
• Define a clear rule for missing products (ignore or cancel).

Checklist for the go-live

• [ ] Connection test successful
• [ ] Payment methods, shipping methods, currencies, tax rates maintained in Shopware
• [ ] Additional fields set and saved in PunchCommerce
• [ ] cXML sender recognises the correct endpoint and authentication
• [ ] Process defined for missing products
• [ ] Test order successfully created

Frequently asked questions (FAQ)

**Why are no options visible after a reload? The lists only load after clicking on "Test". However, your saved values are retained.

**Can I configure multiple target systems? Yes, one target system per profile. Multiple profiles are possible.

**Do I have to fill in all additional fields? No, but recommended. Defaults make the process more robust.

**Why "PUNCH-" in the order number? This makes it easy to identify orders from PunchCommerce in the Shopware backend.

**How secure is my data? Secrets are stored confidentially, only encrypted connections (HTTPS) are permitted.

Troubleshooting (error search)

• Connection test fails:
  • URL correct? Accessible via HTTPS?
  • Access key/secret correct and with sufficient rights?
  • Firewall/proxy blocked POST /api/oauth/token?
• Options (payment/shipping/currency/tax) empty:
  • Execute "Test"; corresponding entities must exist and be active in Shopware.
• Order is rejected in Shopware due to invalid IDs:
  • Old IDs saved in PunchCommerce? Click "Test", select new options, save.
• cXML arrives, but products are missing:
  • Set option "Ignore non-existing products" depending on process requirements. Check product master data in Shopware.
• Timeouts:
  • Check network; try again. With large option tables, the first test may take a little longer.

Technical note: The connection test collects partial successes. It can be "successful" even though individual option lists were not loaded. The notes in the result then provide details.

Please be ready for support enquiries:

• Shopware version & shop URL
• Time & error message
• Screenshots of the settings (without secret)
• Example of a cXML order (anonymised)

This enables us to help you quickly and precisely.