API-Dokumentation

Basis-URL: https://api.normapi.de. Requests und Antworten sind UTF-8; Fehler kommen als RFC-9457-Problem-JSON. Zum Prüfen ist keine Authentifizierung nötig — es gelten die Fair-Use-Limits. Einen eigenen Schlüssel mit eigenem Kontingent (Authorization: Bearer nk_live_…) legen Sie selbst an: Konto anlegen — Magic-Link oder GitHub, keine Kreditkarte, Prüfen bleibt kostenlos und zählt nie aufs Kontingent.

Das Dokument ist der rohe Request-Body — kein Multipart, kein Base64. Der Dateityp wird am Inhalt erkannt, nie am Content-Type-Header. Bei ZUGFeRD/Factur-X-PDFs wird die eingebettete Rechnung extrahiert und geprüft.

curl -X POST https://api.normapi.de/v1/validate \
  -H 'Content-Type: application/xml' \
  -H 'Accept-Language: de' \
  -H 'X-Document-Name: rechnung.xml' \
  --data-binary @rechnung.xml

{
  "acceptable": false,
  "wellFormed": true,
  "schemaValid": true,
  "schematronValid": false,
  "businessRulesEvaluated": true,
  "rulesetVersion": "v2026-08-31",
  "scenario": "EN16931 XRechnung (UBL Invoice)",
  "findings": [
    {
      "code": "BR-CO-16",
      "severity": "ERROR",
      "text": "[BR-CO-16]-Amount due for payment (BT-115) = ...",
      "origin": "SCHEMATRON",
      "location": "/Q{urn:oasis:...:Invoice-2}Invoice[1]/Q{...}LegalMonetaryTotal[1]",
      "line": null, "column": null,
      "test": "(exists(cbc:PrepaidAmount) and not(exists(cbc:Payable...",
      "explanation": {
        "meaning": "Der Zahlbetrag (BT-115) muss rechnerisch aufgehen: ...",
        "cause": "...",
        "fix": "Rechnen Sie Beträge durchgängig mit Dezimalarithmetik, ...",
        "url": "https://normapi.de/fehler/br-co-16"
      }
    }
  ]
}

Die Bedeutung der Felder — drei davon werden regelmäßig missverstanden:

Rechnungsdaten als JSON, validierte XRechnung 3.0.2 zurück — UBL standardmäßig, UN/CEFACT CII mit ?syntax=cii, oder ein komplettes ZUGFeRD-Hybrid-PDF (PDF/A-3 mit eingebetteter Rechnung und menschenlesbarer Seite) mit ?syntax=zugferd. Alle Summen berechnet der Server — Positionsnetto, Steueraufschlüsselung, Gesamtbeträge — in Dezimalarithmetik, sodass die BR-CO-Summenregeln konstruktionsbedingt stimmen. Der klassische E-Rechnungs-Fehler ist Gleitkomma-Arithmetik beim Aufrufer; eine API, die fertige Summen entgegennimmt, würde genau diesen Fehler reproduzieren.

Keine Rechnung verlässt die API ungeprüft: Jedes erzeugte Dokument durchläuft vor der Antwort das offizielle Regelwerk. Eine 200 trägt also ein Dokument, das die Prüfung bestanden hat — beschreibt Ihr JSON eine Rechnung, die die Regeln nicht zulassen, kommt eine 422 mit den Findings.

curl -X POST https://api.normapi.de/v1/invoices \
  -H 'Content-Type: application/json' \
  --data-binary @rechnung.json -o rechnung.xml

# UN/CEFACT CII statt UBL:
curl -X POST 'https://api.normapi.de/v1/invoices?syntax=cii' ...

# ZUGFeRD-Hybrid-PDF (application/pdf):
curl -X POST 'https://api.normapi.de/v1/invoices?syntax=zugferd' \
  -H 'Content-Type: application/json' \
  --data-binary @rechnung.json -o rechnung.pdf

{
  "invoiceNumber": "RE-2026-0815",
  "issueDate": "2026-08-13",
  "dueDate": "2026-09-12",
  "deliveryDate": "2026-08-10",
  "currency": "EUR",
  "buyerReference": "04011000-12345-03",
  "seller": {
    "name": "Muster Software GmbH",
    "vatId": "DE123456789",
    "electronicAddress": "rechnung@muster-software.de",
    "address": { "street": "Beispielstraße 12", "city": "Berlin",
                 "postcode": "10115", "country": "DE" },
    "contact": { "name": "Maria Muster", "phone": "+49 30 1234567",
                 "email": "maria@muster-software.de" }
  },
  "buyer": {
    "name": "Beispiel Handel AG",
    "electronicAddress": "einkauf@beispiel-handel.de",
    "address": { "street": "Handelsweg 3", "city": "Hamburg",
                 "postcode": "20095", "country": "DE" }
  },
  "payment": { "meansCode": "58", "iban": "DE02120300000000202051",
               "reference": "RE-2026-0815" },
  "paymentTerms": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
  "lines": [
    { "name": "Softwarelizenz Jahresabo", "quantity": 3, "unit": "C62",
      "unitPrice": 199.00, "vatCategory": "S", "vatRate": 19 }
  ]
}

Die Antwort ist das XML selbst (Content-Type application/xml) — direkt in eine Datei umleiten und fertig. Zwei Header tragen die Provenienz:

Gutschriften, Korrekturen, Teil- und Schlussrechnungen wählen Sie mit typeCode (BT-3); der Bezug auf die frühere Rechnung steht in precedingInvoices (BG-3). Eine 381 schreibt die API in UBL als CreditNote-Dokument, wie es das Regelwerk verlangt. Beträge bleiben positiv — die Belegart sagt, in welche Richtung das Geld fließt.

"typeCode": "381",
"precedingInvoices": [
  { "number": "RE-2026-0815", "issueDate": "2026-08-13" }
]

Nachlässe und Zuschläge gibt es auf Rechnungsebene (allowances, charges, mit eigener Steuerkategorie) und je Position (ohne Steuerkategorie — es gilt die der Position). Ein Betrag oder ein Prozentsatz; den Betrag aus dem Prozentsatz rechnet der Server, kaufmännisch gerundet, ebenso alle Summen und die Steueraufschlüsselung.

"allowances": [
  { "amount": 9.80, "reason": "Treuerabatt", "reasonCode": "95",
    "vatCategory": "S", "vatRate": 7 }
],
"charges": [
  { "amount": 12.50, "reason": "Versandkosten", "reasonCode": "FC",
    "vatCategory": "S", "vatRate": 19 }
],
"lines": [
  { "name": "Softwarelizenz Jahresabo", "quantity": 3, "unit": "C62",
    "unitPrice": 199.00, "vatCategory": "S", "vatRate": 19,
    "allowances": [
      { "percent": 10, "reason": "Mengenrabatt", "reasonCode": "95" }
    ] }
]

Zahlungswege: Überweisung (58, 30) mit Konto, SEPA-Lastschrift (59) mit Mandat, Kartenzahlung (48, 54, 55) mit Karte — und jeder andere UNTDID-4461-Code ohne weitere Angaben. Zu jedem Weg gehört nur seine eigene Gruppe: Wer per Lastschrift einzieht, lässt die eigene IBAN weg (BR-DE-25-b).

"payment": {
  "meansCode": "59",
  "reference": "RE-2026-0815",
  "directDebit": {
    "mandateReference": "MANDAT-2026-001",
    "creditorId": "DE98ZZZ09999999999",
    "debitedAccount": "DE02120300000000202051"
  }
}

Wenn Ihre Software ihre Rechnungen schon selbst gestaltet, bleibt das Layout: Sie schicken Ihr PDF mit, und NormAPI bettet das geprüfte XML darin ein. Die Anfrage ist multipart, mit den Rechnungsdaten als Teil invoice (dasselbe JSON wie oben) und Ihrem PDF als Teil pdf, bis 5 MB. Die Syntax ist zugferd, die einzige, die ein PDF tragen kann, und darf daher fehlen. Nötig ist ein API-Schlüssel; der Aufruf zählt wie jede andere erzeugte Rechnung einmal.

curl -X POST https://api.normapi.de/v1/invoices \
  -H 'Authorization: Bearer nk_live_…' \
  -F 'invoice=@rechnung.json;type=application/json' \
  -F 'pdf=@ihre-rechnung.pdf;type=application/pdf' \
  -o rechnung.pdf

Zweimal geprüft, bevor es zurückgeht: das XML gegen das Regelwerk, wie jede erzeugte Rechnung, und die fertige Datei mit veraPDF gegen PDF/A-3. Eine Datei, die kein PDF/A-3 werden kann, kommt als 422 zurück; ihre violations nennen die verletzten Abschnitte der ISO 19005-3. Meist sind die Schriften nicht eingebettet: Exportieren Sie das PDF in der Software, die es erzeugt, als PDF/A (1b, 2b oder 3b) und schicken Sie es erneut. Ein PDF, das schon eine E-Rechnung enthält, wird abgelehnt statt überschrieben.

{
  "type": "https://normapi.de/problems/pdf-not-pdfa",
  "title": "PDF cannot become a PDF/A-3",
  "status": 422,
  "violations": [
    { "clause": "6.2.11.4.1", "test": 1, "occurrences": 1,
      "description": "The font programs for all fonts used for rendering within a conforming file shall be embedded ..." }
  ]
}

Nach einem Timeout wissen Sie nicht, ob die Anfrage nie ankam oder ob die Rechnung erzeugt wurde und nur die Antwort verloren ging. Schicken Sie einen Idempotency-Key-Header mit — 1 bis 255 druckbare ASCII-Zeichen, eine UUID oder Ihre Rechnungsnummer — und wiederholen Sie mit demselben Schlüssel. War der erste Aufruf erfolgreich, bekommen Sie die Rechnung noch einmal, markiert mit Idempotent-Replayed: true, und sie wird nicht ein zweites Mal gezählt. Ein Schlüssel gilt 24 Stunden und nur als SHA-256-Wert: Weder er noch die Rechnung werden gespeichert. Er wirkt bei Aufrufen mit API-Schlüssel, denn nur die werden gezählt.

curl -X POST https://api.normapi.de/v1/invoices \
  -H 'Authorization: Bearer nk_live_…' \
  -H 'Idempotency-Key: RE-2026-0815' \
  -H 'Content-Type: application/json' \
  --data-binary @rechnung.json -o rechnung.xml

Eine Wiederholung wird neu erzeugt, nicht aus einem Speicher gelesen, denn gespeichert wird nichts. Die Rechnung ist dieselbe; die internen Zeitstempel eines PDFs können abweichen.

Was acceptable: true bedeutet, hängt vom Dokument ab. Alles Folgende läuft bei jedem Aufruf, sofern nicht anders vermerkt, gegen die offizielle KoSIT-Konfiguration v2026-08-31 (XRechnung 3.0.2); „nicht geprüft“ heißt genau das.

Pflichtfelder sind markiert. Alles Weitere entscheidet das Regelwerk selbst — fehlt etwa beim Verkäufer sowohl USt-IdNr. als auch Steuernummer, kommt eine 422 mit BR-DE-16, nicht ein erfundener eigener Fehlercode.

Party — für Verkäufer und Käufer gleich aufgebaut; was auf welcher Seite Pflicht ist, entscheidet das Regelwerk (der Verkäufer braucht Kontakt und steuerliche Identifikation, der Käufer nicht):

Payment und Line:

AllowanceCharge — ein Nachlass oder Zuschlag auf Rechnungsebene; auf Positionsebene dieselben Felder ohne die drei Steuerangaben:

Fehler sind RFC-9457-Problem-JSON mit type, title, detail und status. Die Statuscodes tragen Bedeutung:

{
  "type": "https://normapi.de/problems/invoice-not-permitted",
  "title": "Invoice not permitted by the rule set",
  "status": 422,
  "rulesetVersion": "v2026-08-31",
  "findings": [
    { "code": "BR-DE-16", "severity": "ERROR",
      "text": "[BR-DE-16] ... Umsatzsteueridentifikationsnummer ...",
      "explanation": { "meaning": "...", "cause": "...",
        "fix": "Tragen Sie mindestens eines der drei Elemente ein. ...",
        "url": "https://normapi.de/fehler/br-de-16" } }
  ]
}

• 30 Anfragen pro Minute je Client, zugleich das Burst-Budget. Darüber: 429 mit Retry-After.
• 5 MB je Dokument — echte E-Rechnungen sind Kilobytes.
• Begrenzte parallele Prüfungen und PDF-Erzeugungen: unter Last antwortet die API schnell mit 503 statt langsam mit Timeouts. Kurz warten und wiederholen.
• Höhere Kontingente für Integrationen: kontakt@normapi.de.

@normapi/client — TypeScript, null Abhängigkeiten, läuft in Node 18+, Browsern, Deno und Bun. Deckt beide Endpunkte ab: validate() und generateInvoice().

npm install @normapi/client

Für KI-Agenten gibt es dieselbe API als MCP-Server — unter https://normapi.com/mcp und als npx @normapi/mcp: MCP-Server einrichten.

import { validate, RateLimitError } from '@normapi/client'
import { readFile } from 'node:fs/promises'

const result = await validate(await readFile('rechnung.xml'))

if (result.acceptable) {
  console.log(`gültig — geprüft als ${result.scenario}`)
} else {
  for (const f of result.findings) {
    console.log(`${f.severity} ${f.code}: ${f.text}`)
  }
}

Für alle anderen Sprachen ist die API bewusst kurz: ein POST mit rohem Body. Die curl-Beispiele oben übersetzen sich in jede HTTP-Bibliothek in wenige Zeilen — hier PHP, weil in diesem Markt viel WooCommerce und JTL läuft.

<?php
$xml = file_get_contents('rechnung.xml');

$ch = curl_init('https://api.normapi.de/v1/validate');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $xml,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/xml',
        'Accept-Language: de',
        'Authorization: Bearer ' . getenv('NORMAPI_KEY'),
    ],
]);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($result['acceptable']) {
    echo "gültig — geprüft als {$result['scenario']}\n";
} else {
    foreach ($result['findings'] as $f) {
        echo "{$f['severity']} {$f['code']}: {$f['text']}\n";
        if ($f['explanation'] !== null) {
            echo "  Lösung: {$f['explanation']['fix']}\n";
        }
    }
}

Sie erzeugen mit horstoeko, Mustang oder einer anderen freien Bibliothek und betreiben den KoSIT-Validator bisher selbst? Der KoSIT-Validator als API zeigt dieselbe Prüfung in PHP, Java und der CI — ohne Java-Installation und ohne Docker.

Die vollständige OpenAPI-Spezifikation (3.1) beschreibt beide Endpunkte, alle Statuscodes und die Feldstruktur — geeignet für Codegeneratoren, Mock-Server und den Import in jedes API-Werkzeug.

openapi.yaml · Postman-Collection

Jede Antwort nennt in rulesetVersion den Regelwerksstand, der das Urteil gefällt hat — aktuell v2026-08-31. Das XRechnung-Regelwerk wird etwa zweimal jährlich aktualisiert; eine heute gültige Rechnung kann gegen ein neues Regelwerk Hinweise oder Fehler produzieren.

Wenn sich der Regelstand ändert, schreiben wir Ihnen: Benachrichtigung abonnieren. Was einzelne Regeln bedeuten und wie man sie behebt: das Fehlercode-Nachschlagewerk. Zum Ausprobieren ohne Code: der Validator.