Gültig ab Version 8.27.0

OCI Bestellfreigabe via cXML

Funktionsbeschreibung

Wenn ein Kunde im angebundenen Beschaffungssystem (z.B. Coupa, SAP Ariba) eine Bestellung aufgibt, wird diese im Shop als "geparkte" OCI-Bestellung angelegt und wartet auf ihre Freigabe durch das Beschaffungssystem.

Die Freigabe erfolgt, indem das Beschaffungssystem ein cXML-Dokument an den Shop sendet. Darin enthalten sind die finale Bestellfreigabe, Adressdaten und die Zuordnung zu den Bestellpositionen.

Endpoint

Die Einlieferung einer "geparkten" OCI-Bestellung, die auf ihre Freigabe wartet, findet über einen POST-Request auf folgende URL statt:

POST https://<shopurl>/oci.php

Der cXML-Inhalt wird als POST-Body oder als Formular-Parameter `~xmlDokument` gesendet.

Zuordnung zur Bestellung

Die Verbindung zwischen dem cXML-Dokument und der geparkten Bestellung im Shop erfolgt über den (Bestellcode).

Der OrderCode wird aus dem Feld SupplierPartID der einzelnen Bestellpositionen (ItemOut) gelesen. Dieser Code entspricht dem Bestellcode, der beim Anlegen der Bestellung im Shop vergeben wurde.

Zusätzlich wird die (orderID) des Beschaffungssystems übernommen und in der Bestellung als Referenz gespeichert.

Verarbeitete Bereiche im cXML-Dokument

1. Externe Bestellnummer (Buyer Order Number)

cXML > Request > OrderRequest > OrderRequestHeader[@orderID]

Das Attribut orderID des OrderRequestHeader-Elements enthält die Bestellnummer aus dem Beschaffungssystem.


`OrderRequestHeader[@orderID]`	`external_order_code`	Externe Bestellnummer des Beschaffungssystems
`OrderRequestHeader[@orderID]`	`OCI_BuyerOrderNumber` (Order-Info)	Zusätzliche Speicherung als Order-Info

2. OrderCode der Bestellpositionen (Zuordnung zum Shop)

cXML > Request > OrderRequest > ItemOut > ItemID > SupplierPartID

Jede ItemOut-Position enthält eine SupplierPartID, die dem Bestellcode der geparkten Bestellung im Shop entspricht.


`ItemOut > ItemID > SupplierPartID`	Bestellcode (z.B. `YFHUYZ`) - identifiziert die Bestellung im Shop
`ItemOut[@quantity]`	Menge der Position

Bei mehreren Positionen wird jede SupplierPartID einzeln verarbeitet und die zugehörige Bestellung freigegeben.

3. Teilenummer (Part Number)

cXML > Request > OrderRequest > ItemOut > ItemID > SupplierPartAuxiliaryID


`ItemOut > ItemID > SupplierPartAuxiliaryID`	`OCI_PARTN` (Order-Info)	Zusätzliche Teilenummer/Referenz

4. Lieferadresse (ShipTo)

cXML > Request > OrderRequest > OrderRequestHeader > ShipTo > Address

Die Lieferadresse wird aus dem ShipTo-Block gelesen und in der Bestellung aktualisiert:


`Address > Name`	`order_DeliverAdressCompany`	Firmenname
`PostalAddress > DeliverTo`	`order_DeliverAdressName`	Empfänger / Ansprechpartner
`PostalAddress > Street`	`order_DeliverAdressStreet`	Strasse und Hausnummer
`PostalAddress > PostalCode`	`order_DeliverAdressZIP`	Postleitzahl
`PostalAddress > City`	`order_DeliverAdressTown`	Stadt
`PostalAddress > Country[@isoCountryCode]`	`order_DeliverAdressCountryCode`	Ländercode (z.B. `DE`), Standard: `DE`
`Address > Email`	`order_DeliverAdressEMail`	E-Mail-Adresse
`Address > Phone`	`order_DeliverAdressTel`	Telefonnummer

5. Rechnungsadresse (BillTo)

cXML > Request > OrderRequest > OrderRequestHeader > BillTo > Address

Die Rechnungsadresse wird aus dem BillTo-Block gelesen und in der Bestellung aktualisiert:


`Address > Name`	`InvoiceAdressCompany1`	Firmenname
`PostalAddress > DeliverTo`	`InvoiceAdressName`	Empfänger / Ansprechpartner
`PostalAddress > Street`	`InvoiceAdressStreet`	Strasse und Hausnummer
`PostalAddress > PostalCode`	`InvoiceAdressZIP`	Postleitzahl
`PostalAddress > City`	`InvoiceAdressTown`	Stadt
`PostalAddress > Country[@isoCountryCode]`	`InvoiceAdressCountryCode`	Ländercode (z.B. `DE`), Standard: `DE`
`Address > Email`	`InvoiceAdressEMail`	E-Mail-Adresse
`Address > Phone`	`InvoiceAdressTel`	Telefonnummer

Antwort (Response)

Der Endpoint antwortet mit einer JSON-Response:

{
    "status": true,
    "order_code": "YFHUYZ",
    "message": "Order status successfully updated."
}

{
    "status": false,
    "order_code": null,
    "message": "Order release failed: <Fehlerbeschreibung>"
}

Moegliche Fehlermeldungen:

invalid xml, cannot be interpreted - Das XML-Dokument konnte nicht gelesen werden
invalid xml, unknown document type - Das Dokumentformat wurde nicht erkannt
invalid status - Es konnte kein gültiger Bestellcode gefunden werden

Beispiel cXML-Dokument

Das folgende Beispiel zeigt ein vollständiges cXML-Dokument mit Testdaten, das für die Bestellfreigabe verwendet werden kann:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML xml:lang="de-DE"
      timestamp="2026-04-12T00:09:00+02:00"
      payloadID="7008201.20260412@testfirma.de"
      version="1.2.014">

    <Header>
        <From>
            <Credential domain="duns">
                <Identity>testfirma</Identity>
            </Credential>
        </From>
        <To>
            <Credential domain="Duns">
                <Identity>123456789</Identity>
            </Credential>
        </To>
        <Sender>
            <Credential domain="duns">
                <Identity>testfirma</Identity>
                <SharedSecret>testfirma-secret</SharedSecret>
            </Credential>
            <UserAgent>Beschaffungssystem 1.0</UserAgent>
        </Sender>
    </Header>

    <Request deploymentMode="production">
        <OrderRequest>
            <OrderRequestHeader orderID="EXT-2026-001"
                                orderDate="2026-04-12T00:09:00+02:00"
                                type="new"
                                orderType="regular">
                <Total>
                    <Money currency="EUR">125,50</Money>
                </Total>

                <!-- Lieferadresse -->
                <ShipTo>
                    <Address isoCountryCode="DE" addressID="1001">
                        <Name xml:lang="de">Musterfirma GmbH</Name>
                        <PostalAddress name="default">
                            <DeliverTo>Max Mustermann</DeliverTo>
                            <Street>Musterstrasse 42</Street>
                            <City>Musterstadt</City>
                            <State></State>
                            <PostalCode>12345</PostalCode>
                            <Country isoCountryCode="DE">Deutschland</Country>
                        </PostalAddress>
                        <Email name="default">max.mustermann@musterfirma.de</Email>
                        <Phone>+49 123 4567890</Phone>
                    </Address>
                </ShipTo>

                <!-- Rechnungsadresse -->
                <BillTo>
                    <Address isoCountryCode="DE" addressID="1002">
                        <Name xml:lang="de">Musterfirma GmbH - Buchhaltung</Name>
                        <PostalAddress name="default">
                            <DeliverTo>Buchhaltung</DeliverTo>
                            <Street>Musterstrasse 42</Street>
                            <City>Musterstadt</City>
                            <State></State>
                            <PostalCode>12345</PostalCode>
                            <Country isoCountryCode="DE">Deutschland</Country>
                        </PostalAddress>
                        <Email name="default">buchhaltung@musterfirma.de</Email>
                        <Phone>+49 123 4567891</Phone>
                    </Address>
                </BillTo>

                <Contact role="endUser">
                    <Name xml:lang="de">Max Mustermann</Name>
                    <Email name="default">max.mustermann@musterfirma.de</Email>
                </Contact>
            </OrderRequestHeader>

            <!-- Bestellposition 1 -->
            <ItemOut quantity="100" lineNumber="1">
                <ItemID>
                    <!-- SupplierPartID = Bestellcode im Shop -->
                    <SupplierPartID>ABCDEF</SupplierPartID>
                    <SupplierPartAuxiliaryID>REF-2026-001</SupplierPartAuxiliaryID>
                </ItemID>
                <ItemDetail>
                    <UnitPrice>
                        <Money currency="EUR">1,25</Money>
                    </UnitPrice>
                    <Description xml:lang="de">Visitenkarten 85x55mm, 4/4-farbig</Description>
                    <UnitOfMeasure>EA</UnitOfMeasure>
                </ItemDetail>
            </ItemOut>

        </OrderRequest>
    </Request>
</cXML>

Format cXML Datei - OCI Freigabe