Endpunkte

Basis-URL: https://app.xingen.de/api — jeder Pfad unten ist relativ dazu (z. B. ist POST /v1/invoices/validate gleichbedeutend mit POST https://app.xingen.de/api/v1/invoices/validate).

Die Validierung erfolgt asynchron. Jeder Submit-Endpunkt liefert sofort 202 Accepted mit einer Rechnungs-id; fragen Sie GET /v1/invoices/{id} ab, bis status nicht mehr processing ist. Ausnahme sind Sandbox-Keys (xgn_test_) — sie liefern sofort ein vorgefertigtes Ergebnis. Siehe Authentifizierung.

POST /v1/invoices/validate

Lädt eine UBL-XML-, CII-XML- oder ZUGFeRD-PDF/A-3-Datei zur Validierung hoch.

Anfrage

Antwort

{
  "id": "3f9e2b7a-2c1d-4a6e-9b3f-8d1e2c4a6b7c",
  "status": "processing"
}

POST /v1/invoices/validate/idoc

Lädt eine SAP-IDoc-XML-Datei hoch. Sie wird vor Anwendung der EN-16931-Regeln in xingens kanonisches Rechnungsmodell konvertiert. Gleiches Anfrage-/Antwortformat wie oben (Formularfelder file + profile, 202 mit {id, status}).

POST /v1/invoices/validate/odata

Übermittelt ein SAP-S/4HANA-OData-SupplierInvoice-Payload direkt — nützlich, wenn Sie Rechnungen per OData aus SAP lesen, statt Dateien zu exportieren.

Anfrage

Antwort

{
  "id": "8b1a4c2e-...",
  "status": "processing"
}

POST /v1/invoices

Übermittelt Rechnungsdaten als strukturiertes JSON, statt selbst XML zu erzeugen — nützlich, wenn Ihr System die Rechnung bereits als Daten statt als Dokument vorliegen hat.

Request-Body

{
  "invoiceNumber": "INV-2024-0042",
  "issueDate": "2024-03-15",
  "currency": "EUR",
  "buyerReference": "991-12345-06",
  "validationProfile": "XRECHNUNG",
  "supplier": { "name": "Acme GmbH", "vatId": "DE123456789", "leitwegId": null },
  "buyer": { "name": "Contoso AG", "vatId": "DE987654321", "leitwegId": "991-12345-06" },
  "lines": [
    { "description": "Software License Q1", "quantity": 5, "unit": "C62", "price": 199.00, "taxRate": 19 }
  ]
}

Antwort

{
  "id": "9c2d5e1a-...",
  "status": "processing"
}

POST /v1/invoices/extract

Lädt eine einfache (nicht XRechnung-/UBL-/CII-)Rechnungs-PDF hoch — auch gescannte/bildbasierte PDFs — zur KI-gestützten Felderkennung mit Claude. Die extrahierte Rechnung wird validiert und in eine ZUGFeRD-/Factur-X-Hybrid-PDF umgewandelt, herunterladbar über GET /v1/invoices/{id}/download, sobald die Verarbeitung abgeschlossen ist. Dies ist dieselbe Konvertierung, die auch die Dashboard-Oberfläche im Hintergrund nutzt — dieser Endpunkt erlaubt es, sie zu automatisieren.

Anfrage

Antwort

{
  "id": "1a2b3c4d-...",
  "status": "processing"
}

Liefert 403, wenn tier=ACCURATE mit einem Free-Plan angefragt wird.

GET /v1/invoices/{id}

Fragen Sie dies ab, um das Validierungsergebnis zu erhalten. status ist eines von processing, validated oder failed_validation.

Antwort

{
  "id": "3f9e2b7a-2c1d-4a6e-9b3f-8d1e2c4a6b7c",
  "status": "failed_validation",
  "validationProfile": "XRECHNUNG",
  "invoiceFormat": "UBL",
  "sandbox": false,
  "createdAt": "2024-03-01T10:00:00Z",
  "canonicalJson": { "invoiceNumber": "INV-2024-0042", "issueDate": "2024-03-15", "..." : "..." },
  "validationResult": {
    "valid": false,
    "errors": [
      {
        "code": "BR-01",
        "message": "An Invoice shall have a Specification identifier.",
        "field": "/Invoice/CustomizationID",
        "suggestion": "Add <cbc:CustomizationID>urn:cen.eu:en16931...</cbc:CustomizationID>",
        "documentationUrl": "https://...",
        "layer": "CORE",
        "severity": "ERROR"
      }
    ],
    "kositResult": { "valid": false, "errors": [] }
  }
}

Beachten Sie: Es gibt keine Zeilennummer (line) in den Fehlern — field gibt stattdessen den betroffenen Pfad an. Siehe die Fehler-Referenz für das vollständige Fehlerformat und gängige Codes.

GET /v1/invoices

Paginierte Liste Ihrer eigenen Rechnungen (aller Rechnungen, falls Sie Super-Admin sind).

GET /v1/invoices/{id}/download

Exportiert eine validierte Rechnung als ZUGFeRD-konforme PDF mit eingebettetem XML (application/pdf).

GET /v1/invoices/{id}/download/idoc

Exportiert eine validierte Rechnung als SAP-IDoc-XML-Datei (application/xml).

API-Key-Verwaltung

POST /v1/api-keys, GET /v1/api-keys, DELETE /v1/api-keys/{id} — Details zu Anfrage/Antwort finden Sie unter Authentifizierung.