# 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](#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](/docs/json-webhook)).
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](/docs/api-reference)):

| 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.
