Erste Schritte

Diese Anleitung führt in weniger als fünf Minuten zum ersten Xingen-API-Aufruf. Im Null-Komma-Nix XRechnung validieren und die strukturierte Response analysieren.

Voraussetzungen

• Ein kostenloses Xingen-Konto — hier registrieren
• Ein API-Key (im Konto-Dashboard generiert)
• curl oder ein beliebiger HTTP-Client

Schritt 1 — API-Key holen

Nach der Registrierung zu Einstellungen → API-Keys navigieren und einen neuen Schlüssel erstellen. Wichtig: Der API-Key sollte an einem sicheren Ort abgespeichert werden — er wird nicht erneut angezeigt.

export XINGEN_API_KEY="xgn_live_ihr_schluessel_hier"

Schritt 2 — Rechnungsdatei vorbereiten

Xingen akzeptiert UBL 2.1 XML, CII XML oder ein ZUGFeRD-eingebettetes PDF/A-3. Speichere das minimale XRechnung-Gerüst unten als rechnung.xml:

<?xml version="1.0" encoding="UTF-8"?>
<ubl:Invoice xmlns:ubl="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
             xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0</cbc:CustomizationID>
  <cbc:ID>RE-2024-001</cbc:ID>
  <cbc:IssueDate>2024-03-01</cbc:IssueDate>
  <!-- ... restliche Pflichtfelder ... -->
</ubl:Invoice>

Schritt 3 — Zur Validierung einreichen

Senden Sie die Datei als multipart/form-data an /v1/invoices/validate, zusammen mit dem zu prüfenden Profil:

curl -X POST https://app.xingen.de/api/v1/invoices/validate \
  -H "Authorization: Bearer $XINGEN_API_KEY" \
  -F "file=@rechnung.xml" \
  -F "profile=XRECHNUNG"

Die Validierung läuft asynchron. Dies liefert sofort 202 Accepted mit einer Rechnungs-ID — das Ergebnis ist noch nicht enthalten:

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

Schritt 4 — Ergebnis abfragen

Fragen Sie GET /v1/invoices/{id} ab, bis status nicht mehr processing ist:

curl https://app.xingen.de/api/v1/invoices/3f9e2b7a-2c1d-4a6e-9b3f-8d1e2c4a6b7c \
  -H "Authorization: Bearer $XINGEN_API_KEY"

Sobald fertig, ist status entweder validated oder failed_validation, und validationResult ist befüllt:

{
  "id": "3f9e2b7a-2c1d-4a6e-9b3f-8d1e2c4a6b7c",
  "status": "failed_validation",
  "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>",
        "severity": "ERROR"
      }
    ]
  }
}

Falls Sie einen Sandbox-Key (xgn_test_) verwendet haben, liegt das Ergebnis sofort vor — mit einem festen, fiktiven validated-Ergebnis statt echter Validierung. Siehe Authentifizierung. Andernfalls enthält errors strukturierte Fehlerobjekte mit Feldpfaden und Korrekturvorschlägen. Siehe die Fehler-Referenz für die vollständige Liste.

Nächste Schritte

• Authentifizierung — Sandbox- vs. Live-Keys, planabhängige Profile, Rotation
• Endpunkte — jeder Endpunkt, inklusive JSON- und SAP-Einreichung
• Formate — unterstützte Ein-/Ausgabekombinationen
• SDKs — offizielle Client-Bibliotheken für Java, Python, TypeScript, C#, PHP und Go
• API-Referenz (Swagger UI) ↗ — interaktiv, alle Endpunkte direkt ausprobieren
• OpenAPI-Spec (JSON) ↗ — Roh-Spezifikation, direkt in Postman oder Codegen-Tools importierbar