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)
- 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.
- Abholung konfigurieren — auf der Pipeline-Seite stellen Sie den Eingang auf
FTP/SFTP-Pull um und geben Verzeichnis und Dateimuster an (z.B.
RE_*.xmlfür Rechnungen). Pro Belegtyp empfiehlt sich ein eigenes Verzeichnis oder Dateimuster. Orderport prüft alle 5 Minuten auf neue Dateien. - 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.
- Belegnummer-Pfad (z.B.
- Mapping erstellen — im Feldmapping ordnen Sie Ihre XML-Pfade den
cXML-Zielfeldern zu. Pflichtfelder: Belegnummer (
Invoice.InvoiceIDbzw.Confirmation.ConfirmID), die referenzierte Bestellnummer (Invoice.OrderID/Confirmation.OrderID) und mindestens eine Position. - 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. - 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
- 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.
- Credential erzeugen — im letzten Wizard-Schritt oder später auf der Pipeline-Seite einen Bearer Token oder ein HMAC-Secret anlegen (siehe JSON-Webhooks).
- Outbound-Credential und Transport anlegen — wie oben in Schritt 5 und 6.
- Belege senden —
POSTan die Webhook-URL der Pipeline mitContent-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.