Belegausgang (cXML)

Mit dem Add-on Belegausgang (cXML) kehrt Orderport die gewohnte Richtung um: Statt Bestellungen zu empfangen, übernimmt Orderport Folgebelege — Bestellbestätigungen, Rechnungen und Gutschriften — aus Ihrem System, wandelt sie in cXML und stellt sie an Beschaffungsnetzwerke wie SAP Ariba oder Coupa zu.

Ihr System liefert die Belege auf einem von zwei Wegen:

  • ERP-XML per FTP/SFTP — Orderport holt Dateien in Ihrem eigenen XML-Format ab. Das Mapping beschreiben Sie anhand eines Beispieldokuments (Ablauf unten).
  • JSON per API — Ihr System schickt die Belege im festen Orderport-JSON-Format an die Webhook-URL der Pipeline. Das Mapping auf cXML ist vorbelegt (Belege per JSON senden).
Belegtyp Erzeugtes cXML-Dokument
Bestellbestätigung ConfirmationRequest
Rechnung InvoiceDetailRequest (purpose standard)
Teilrechnung InvoiceDetailRequest — normale Rechnung mit Teilmengen gegen dieselbe Bestellung
Gutschrift InvoiceDetailRequest (purpose lineLevelCreditMemo, negative Beträge)

So funktioniert es (ERP-XML per FTP/SFTP)

  1. Pipeline pro Belegtyp anlegen — im Experten-Wizard wählen Sie in Schritt 1 den Dokumenttyp (z.B. „Rechnung"). Als Eingangsformat steht Generisches XML zur Verfügung, als Ausgangsformat cXML.
  2. Abholung konfigurieren — auf der Pipeline-Seite stellen Sie den Eingang auf FTP/SFTP-Pull um und geben Verzeichnis und Dateimuster an (z.B. RE_*.xml für Rechnungen). Pro Belegtyp empfiehlt sich ein eigenes Verzeichnis oder Dateimuster. Orderport prüft alle 5 Minuten auf neue Dateien.
  3. XML-Eingang beschreiben — hinterlegen Sie ein Beispieldokument Ihres XML-Formats; daraus ermittelt Orderport die Quellfelder für das Mapping und die KI-Vorschläge. Zusätzlich konfigurieren Sie:
    • Belegnummer-Pfad (z.B. Rechnung.Kopf.Nummer) — für die Duplikat-Erkennung.
    • Positions-Pfad (z.B. Rechnung.Positionen.Position) — damit auch Belege mit nur einer Position korrekt gemappt werden.
  4. Mapping erstellen — im Feldmapping ordnen Sie Ihre XML-Pfade den cXML-Zielfeldern zu. Pflichtfelder: Belegnummer (Invoice.InvoiceID bzw. Confirmation.ConfirmID), die referenzierte Bestellnummer (Invoice.OrderID / Confirmation.OrderID) und mindestens eine Position.
  5. Outbound-Credential anlegen — auf der Pipeline-Seite unter Outbound-Credentials: From-/To-Identity (z.B. Ihre Supplier-ANID und die Buyer-ANID), SharedSecret und den Deployment-Modus (test / production). Jede Beleg-Pipeline hat genau eine Outbound-Credential; das SharedSecret wird verschlüsselt gespeichert.
  6. Transport anlegen — HTTP POST an die Empfangs-URL des Netzwerks. Orderport prüft die cXML-Antwort des Empfängers: Ein innerer Status ≥ 300 gilt als fehlgeschlagene Zustellung und löst die normale Retry-Kette aus (1 min / 5 min / 30 min / 2 h / 24 h).

Belege per JSON senden

  1. Pipeline pro Belegtyp anlegen — im Experten-Wizard den Dokumenttyp wählen, als Eingangsformat Generisches JSON, als Ausgangsformat cXML. Das Mapping ist vollständig vorbelegt — der Mapping-Editor zeigt genau die Regeln, mit denen Orderport arbeitet, und Sie können sie anpassen.
  2. Credential erzeugen — im letzten Wizard-Schritt oder später auf der Pipeline-Seite einen Bearer Token oder ein HMAC-Secret anlegen (siehe JSON-Webhooks).
  3. Outbound-Credential und Transport anlegen — wie oben in Schritt 5 und 6.
  4. Belege senden — POST an die Webhook-URL der Pipeline mit Content-Type: application/json.
POST https://orderport.app/api/v1/webhook/{token}
Authorization: Bearer ot_bearer_a1b2c3d4...
Content-Type: application/json

{
  "document_number": "RE-2026-0042",
  "document_date": "2026-10-07",
  "delivery_date": "2026-10-06",
  "currency": "EUR",
  "order_reference": { "number": "PO-4711", "date": "2026-10-01" },
  "supplier": { "name": "Muster Schrauben GmbH", "street": "Industriestraße 5",
                "postal_code": "70565", "city": "Stuttgart", "country": "DE",
                "vat_id": "DE123456789" },
  "buyer": { "name": "Beispiel Maschinenbau AG", "street": "Werkstraße 12",
             "postal_code": "80331", "city": "München", "country": "DE" },
  "items": [
    { "line_number": 1, "quantity": 10, "unit": "EA", "sku": "ART-100",
      "description": "Sechskantschraube M8x40", "unit_price_net": 1.50, "line_total_net": 15.00 }
  ],
  "taxes": [ { "rate": 19, "taxable_amount": 15.00, "tax_amount": 2.85 } ],
  "payment_terms": [ { "days": 14, "discount_percent": 2 }, { "days": 30 } ],
  "totals": { "net_amount": 15.00, "tax_amount": 2.85, "gross_amount": 17.85 }
}

Der Belegtyp ergibt sich aus der Pipeline, nicht aus dem Payload. Die Felder im Überblick (vollständige Schemas und Beispiele in der API-Referenz):

Feld Bestätigung Rechnung Gutschrift
document_number, document_date, currency Pflicht Pflicht Pflicht
order_reference.number (Bestellnummer des Einkäufers) Pflicht Pflicht Pflicht
order_reference.payload_id (payloadID der cXML-Bestellung) optional optional optional
items[] mit line_number, quantity, unit je nach Typ¹ Pflicht Pflicht
items[].unit_price_net, items[].line_total_net — Pflicht Pflicht
items[].sku, items[].description — optional optional
supplier (name, street, postal_code, city, country) + vat_id oder tax_number — Pflicht Pflicht
buyer (name, street, postal_code, city, country), buyer.vat_id optional — Pflicht Pflicht
delivery_date (Leistungsdatum) — Pflicht optional
taxes[] mit rate, taxable_amount, tax_amount (je Steuersatz) — Pflicht Pflicht
payment_terms[] mit days, discount_percent (Skonto) — optional optional
totals.net_amount, totals.tax_amount — Pflicht Pflicht
totals.gross_amount optional Pflicht Pflicht
totals.shipping_amount, totals.due_amount — optional optional
confirmation_type (accept, detail, except, backordered, reject) Pflicht — —
operation (new, update) optional — —
items[].status, items[].delivery_date, items[].shipment_date, items[].comment optional — —
items[].unit_price_net (nur bei geändertem Preis) optional Pflicht Pflicht
original_invoice_number — — Pflicht
original_invoice_date, original_invoice_payload_id — — optional

¹ Pflicht bei detail und except, verboten bei reject, sonst optional.

Jedes Feld der Tabelle landet im cXML. Felder außerhalb der Tabelle ignoriert Orderport. Datumsangaben ohne Uhrzeit überträgt Orderport als 12:00 Uhr deutscher Zeit — so bleibt der Kalendertag beim Einkäufer in jeder Zeitzone derselbe.

Bezug auf die Bestellung. cXML verweist auf die ursprüngliche Bestellung über deren payloadID. Ist die Bestellung über Orderport eingegangen, setzt Orderport sie selbst ein — Sie müssen nichts tun. Hat die Bestellung Ihr System auf anderem Weg erreicht, übergeben Sie sie in order_reference.payload_id.

Orderport prüft jeden Beleg beim Empfang. Fehlt ein Pflichtfeld, stimmt ein Typ nicht oder gehen die Summen einer Rechnung nicht auf, antwortet der Webhook sofort mit HTTP 422 und nennt jedes fehlerhafte Feld — es entsteht keine Nachricht, Ihr System kann den Beleg korrigiert erneut senden. Nachgerechnet wird, was auch der Einkäufer nachrechnet (ein Cent Rundung ist erlaubt): Positionen = net_amount, Summe der taxes = tax_amount, Bemessungsgrundlagen = net_amount + shipping_amount, und net_amount + shipping_amount + tax_amount = gross_amount.

Gutschriften senden Sie mit positiven Mengen und Beträgen — Orderport überträgt sie negativ, so wie cXML es verlangt.

Duplikat-Erkennung

Die Belegnummer aus dem konfigurierten Pfad (bei JSON: document_number) dient als eindeutiger Schlüssel pro Pipeline: Eine erneut abgelegte Datei mit derselben Rechnungsnummer wird nicht noch einmal zugestellt. Ausnahme: eine Bestätigung mit operation: update — sie ist eine gewollte Korrektur. Teilrechnungen erhalten eigene Rechnungsnummern und sind dadurch automatisch keine Duplikate.

Die Belegarten im Detail

Jede Belegart läuft über eine eigene Pipeline mit eigenem Mapping. Die Zielfelder unterscheiden sich je Belegart; fehlende Pflichtfelder führen zu einer klaren Fehlermeldung (Status „fehlgeschlagen"), bevor irgendetwas versendet wird.

Auftragsbestätigung (ConfirmationRequest)

Bestätigt die Bestellung des Einkäufers — komplett, mit Abweichungen, im Rückstand oder als Ablehnung.

Zielfeld Bedeutung Pflicht
Confirmation.OrderID Bestellnummer des Einkäufers (Bezug) ja
Confirmation.ConfirmID Ihre Bestätigungsnummer nein (bei Korrekturen ja)
Confirmation.NoticeDate Bestätigungsdatum (Default: Verarbeitungszeit) nein
Confirmation.Type accept, detail, except, backordered oder reject (Default detail) nein
Confirmation.Operation update für eine Korrektur (Default new) nein
Confirmation.OrderDate / Confirmation.Comment Bestelldatum / Kommentar (bei reject der Ablehnungsgrund) nein
Confirmation.OrderPayloadID payloadID der cXML-Bestellung (Default: von Orderport ermittelt) nein
Total.Amount / Total.Currency neuer Gesamtbetrag — nur bei geänderter Menge oder Preis nein
Items.LineNumber, Items.Quantity, Items.UnitOfMeasure Position und Menge bei detail/except
Items.Status accept, detail, backordered, reject, unknown nein
Items.DeliveryDate, Items.ShipmentDate Liefer- und Versanddatum nein
Items.UnitPrice, Items.Comment geänderter Einzelpreis netto, Kommentar zur Position nein

Welche Positionsstatus erlaubt sind, hängt vom Typ ab — so verlangt es cXML:

Confirmation.Type Bedeutung Positionen
accept Bestellung unverändert angenommen optional, nur Status accept (z. B. für Liefertermine)
detail Änderungen an den genannten Positionen Pflicht, jeder Status
except angenommen, Ausnahmen in den genannten Positionen Pflicht, jeder Status
backordered ganze Bestellung im Rückstand optional, nur Status backordered
reject ganze Bestellung abgelehnt keine — Grund in Confirmation.Comment

Ohne Status gilt eine Position als accept (bei backordered als backordered). Status detail braucht einen geänderten Liefertermin oder Einzelpreis.

Teilmengen. Für Teillieferungen und Teilablehnungen kommt dieselbe Positionsnummer mehrfach vor — jede Zeile mit eigener Menge, eigenem Status und Termin, z. B. 6 Stück accept zum 14.10. und 4 Stück detail zum 21.10. Orderport fasst sie zu einer cXML-Position zusammen. Die Mengen einer Position müssen sich zur bestellten Menge summieren — eine nicht lieferbare Restmenge geben Sie als eigene Zeile mit reject oder backordered an.

Korrekturen. Eine bereits zugestellte Bestätigung korrigieren Sie mit operation: update (JSON) bzw. Confirmation.Operation = update und derselben Belegnummer. Die Korrektur ersetzt die erste Fassung beim Einkäufer vollständig — senden Sie also alle Positionen erneut. Orderport verweist dabei automatisch auf die zuletzt zugestellte Fassung; gibt es keine, schlägt die Korrektur mit klarer Meldung fehl.

Rechnung (InvoiceDetailRequest)

Die elektronische Rechnung gegen die Bestellung, mit Positionsdaten, Summen und Umsatzsteuer.

Zielfeld Bedeutung Pflicht
Invoice.InvoiceID Ihre Rechnungsnummer (Dedup-Schlüssel) ja
Invoice.OrderID Bestellnummer des Einkäufers (Bezug) ja
Items.* mindestens eine Position (LineNumber, Quantity, UnitOfMeasure, SupplierPartID, Description, UnitPrice, SubtotalAmount) ja (≥ 1)
Items.UnitPrice Einzelpreis netto — cXML verlangt ihn je Position ja
Invoice.InvoiceDate Rechnungsdatum (Default: Verarbeitungszeit) nein
Invoice.DeliveryDate Leistungsdatum, übertragen als taxPointDate für §14 UStG
Supplier.* (Name, Street, PostalCode, City, Country, VatID, TaxNumber) Rechnungsaussteller (InvoicePartner issuerOfInvoice) für §14 UStG
Buyer.* (Name, Street, PostalCode, City, Country, VatID) Rechnungsempfänger (InvoicePartner soldTo) für §14 UStG
Taxes.Rate, Taxes.TaxableAmount, Taxes.TaxAmount ein TaxDetail je Steuersatz (z. B. 19 % und 7 %) empfohlen
Summary.TaxRate statt Taxes.*, wenn es nur einen Steuersatz gibt —
PaymentTerms.Days, PaymentTerms.DiscountPercent Zahlungsziel und Skonto nein
Summary.Currency Währung (Default EUR) nein
Summary.SubtotalAmount Nettosumme (Default: Summe der Positionen) nein
Summary.ShippingAmount Versandkosten netto nein
Summary.TaxAmount, Summary.TaxDescription Steuer gesamt, Bezeichnung (Default „Umsatzsteuer") empfohlen
Summary.GrossAmount Bruttosumme (Default: Netto + Versand + Steuer) nein
Summary.NetAmount, Summary.DueAmount Betrag nach Rabatt und fälliger Betrag (Default: Bruttosumme) nein

Orderport deckt die Umsatzsteuer mit einem oder mehreren Steuersätzen ab. Steuerbefreite Umsätze und Sonderfälle wie Reverse Charge sind bewusst ausgeklammert — sprechen Sie uns an.

Teilrechnung

Teilrechnungen sind normale Rechnungen mit eigener Rechnungsnummer und Teilmengen gegen dieselbe Bestellung — genau so sehen es cXML und die Netzwerke vor, ein Sonderformat existiert nicht. Sie laufen über dieselbe Rechnungs-Pipeline; dank eigener Belegnummer greift die Duplikat-Erkennung korrekt. Beachten Sie, dass manche Einkäufer kumulierte Mengen gegen die Bestellung prüfen.

Gutschrift (InvoiceDetailRequest, purpose="lineLevelCreditMemo")

Gutschriften nutzen dieselben Zielfelder wie Rechnungen, plus:

Zielfeld Bedeutung Pflicht
Invoice.OriginalInvoiceID Nummer der Originalrechnung → InvoiceIDInfo ja
Invoice.OriginalInvoiceDate Datum der Originalrechnung empfohlen
Invoice.OriginalInvoicePayloadID payloadID der Originalrechnung (Default: von Orderport ermittelt) nur wenn nicht über Orderport zugestellt

Standardmäßig erzeugt Orderport eine positionsbezogene Gutschrift (purpose="lineLevelCreditMemo"): Sie verweist per DocumentReference auf die Originalrechnung. Hat Orderport diese Rechnung zugestellt, setzt es den Verweis selbst; sonst geben Sie ihre payloadID mit — fehlt sie, schlägt die Gutschrift mit klarer Meldung fehl.

Vorzeichen: cXML verlangt für Gutschriften negative Beträge. Orderport setzt sie selbst — egal, ob Ihr System positive oder negative Werte liefert. Mengen werden negativ, Einzelpreise bleiben positiv; Positionssummen, Steuer, Brutto- und fälliger Betrag werden negativ.

In der Outbound-Credential der Pipeline lässt sich die Variante umstellen: creditMemo (Gutschrift auf Belegebene ohne Positionen) oder standard (Rechnung mit negativen Beträgen) — nur auf Wunsch des Einkäufers.

Hinweise

  • Laden Sie Dateien auf dem SFTP-Server atomar hoch (temporärer Name, dann umbenennen), damit keine halb geschriebenen Dateien abgeholt werden.
  • Nutzen Sie pro Belegart ein eigenes Dateimuster (z. B. AB_*.xml, RE_*.xml, GS_*.xml) oder eigene Verzeichnisse, damit jede Datei in der richtigen Pipeline landet.