API-Dokumentation

Basis-URL: https://api.normapi.de. Requests und Antworten sind UTF-8; Fehler kommen als RFC-9457-Problem-JSON. Zum Prüfen und Auslesen 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 und Auslesen bleiben kostenlos und zählen nie aufs Kontingent.

Dieselben drei als Werkzeuge für KI-Agenten, in Claude, ChatGPT, Cursor oder VS Code: der MCP-Server.

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.com/de/fehler#BR-CO-16"
      }
    }
  ]
}

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

Der Rückweg zu POST /v1/invoices: Eine eingegangene E-Rechnung — XRechnung oder jede andere EN-16931-Rechnung als UBL oder CII, ein ZUGFeRD- oder Factur-X-PDF — kommt als JSON zurück. Der Endpunkt nimmt genau das an, was POST /v1/validate annimmt: das Dokument als rohen Body, am Inhalt erkannt, bis 5 MB. Aus einem PDF wird die eingebettete Rechnung gelesen. Auslesen ist kostenlos, braucht keinen Schlüssel und zählt nie aufs Kontingent.

curl -X POST https://api.normapi.de/v1/parse \
  -H 'Content-Type: application/pdf' \
  --data-binary @eingang.pdf

{
  "syntax": "cii",
  "documentKind": "invoice",
  "source": { "kind": "pdf", "attachment": "xrechnung.xml" },
  "specificationId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
  "businessProcess": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
  "profile": "xrechnung",
  "invoice": {
    "invoiceNumber": "RE-2026-1001",
    "issueDate": "2026-10-01",
    "typeCode": "380",
    "dueDate": "2026-10-31",
    "currency": "EUR",
    "buyerReference": "4500012345",
    "seller": { "name": "Muster Software GmbH", "vatId": "DE123456789", ... },
    "buyer": { "name": "Beispiel Handel AG", ... },
    "payment": { "meansCode": "58", "iban": "DE17100500000123456789", ... },
    "lines": [
      { "id": "1", "name": "Softwareentwicklung ERP-Schnittstelle",
        "quantity": 24, "unit": "HUR", "unitPrice": 95.00,
        "vatCategory": "S", "vatRate": 19, ... },
      ...
    ],
    ...
  },
  "stated": {
    "lineTotal": "2940.00",
    "netTotal": "2940.00",
    "vatTotal": "558.60",
    "grossTotal": "3498.60",
    "amountDue": "3498.60",
    "vatBreakdown": [
      { "category": "S", "rate": "19.00",
        "taxableAmount": "2940.00", "vatAmount": "558.60", ... }
    ],
    "lines": [{ "netAmount": "2280.00", ... }, { "netAmount": "660.00", ... }],
    ...
  },
  "notMapped": [],
  "validation": null
}

import { generateInvoice, parse } from '@normapi/client'
import { readFile } from 'node:fs/promises'

const { invoice, stated, notMapped, profile } = await parse(await readFile('eingang.pdf'))

console.log(invoice.invoiceNumber, invoice.seller?.name, stated.amountDue)
for (const entry of notMapped) {
  console.log(`nicht übernommen: ${entry.path} (${entry.count}×)`)
}

// Eine eigene Rechnung korrigieren: auslesen, ändern, neu erzeugen —
// nach denselben Regeln, auf die sich das Original beruft.
const { xml } = await generateInvoice(
  {
    ...invoice,
    invoiceNumber: 'RE-2026-1001-K',
    typeCode: '384',
    precedingInvoices: [{ number: invoice.invoiceNumber, issueDate: invoice.issueDate }],
  },
  { apiKey: process.env.NORMAPI_KEY, ...(profile === null ? {} : { profile }) },
)

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. Jedes nennt neben der Regel in fields die Felder Ihres JSON, die sie betrifft, etwa buyer.vatId oder lines[1].unit — auch ein fehlendes Feld wie buyerReference.

Für Unternehmen: profile=en16931. Ohne Angabe entsteht eine XRechnung, wie Behörden sie verlangen. Sie fügt der EN 16931 drei Dinge hinzu: die Käuferreferenz (bei Behörden die Leitweg-ID, BR-DE-15), einen Ansprechpartner des Verkäufers (BR-DE-2) und die elektronischen Adressen beider Seiten. Zwischen Unternehmen genügt nach § 14 UStG die Norm selbst: Mit ?profile=en16931 dürfen diese Angaben fehlen, geprüft wird gegen die EN-16931-Regeln (Szenario „EN16931 (UBL Invoice)“ oder „EN16931 (CII)“), und ein ZUGFeRD-PDF trägt das Profil EN 16931.

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

# Für ein Unternehmen: EN 16931, Leitweg-ID, Ansprechpartner und E-Mail-Adressen optional
curl -X POST 'https://api.normapi.de/v1/invoices?syntax=zugferd&profile=en16931' ...

{
  "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. Zwei häufige Gründe richtet NormAPI vorher selbst, ohne dass sich die Seite ändert: Helvetica und Arial ohne eingebettete Schrift bekommen die maßgleiche Liberation Sans eingebettet, und Bilder verlieren die Angaben, die PDF/A verbietet (Interpolate, Alternates, OPI). Eine Datei, die danach kein PDF/A-3 werden kann, kommt als 422 zurück; ihre violations nennen die verletzten Abschnitte der ISO 19005-3. Meist ist eine andere Schrift 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. Jede Ablehnung Ihres PDFs trägt neben dem Text ein Feld reason, auf das Ihr Programm prüfen kann: not-pdfa, uncheckable, unreadable, already-invoice, not-rewritable, too-large oder not-pdf.

{
  "type": "https://normapi.de/problems/pdf-not-pdfa",
  "title": "PDF cannot become a PDF/A-3",
  "status": 422,
  "reason": "not-pdfa",
  "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 ..." }
  ]
}

Ein ZUGFeRD-PDF auf unserer Seite (?syntax=zugferd, ohne Ihr eigenes PDF) druckt NormAPI auf den Briefkopf Ihres Kontos, wenn es einen hat, mit der Anschrift des Empfängers im Fenster des Briefumschlags. Sie laden den Briefkopf einmal als PDF hoch, im Konto unter Briefkopf. Hochladen, Ersetzen und Löschen gibt es nur dort; die API hat dafür keinen Endpunkt. Der Briefkopf ist in jedem Tarif enthalten, auch im kostenlosen, und die Rechnungen darauf zählen wie jede andere erzeugte Rechnung. XRechnung (UBL oder CII) hat keine Seite und bleibt unverändert.

Hochgeladen wird eine PDF-Datei bis 5 MiB mit einer oder zwei Seiten im A4-Hochformat, mit Bildern bis 10 Megapixel in Farbe (30 in Graustufen) und Zeichnungen bis 512 KiB je Seite. Die erste Seite ist der Briefkopf der ersten Rechnungsseite, die zweite der Briefkopf der Folgeseiten; hat die Datei nur eine Seite, gilt sie für alle Seiten. Im Konto legen Sie auch fest, ob der Briefkopf für alle Rechnungen des Kontos gilt oder nur für einen Verkäufer (USt-IdNr., Steuernummer oder Name; es genügt, wenn eine Angabe mit der Rechnung übereinstimmt).

# Auf dem Briefkopf des Kontos, wenn es einen hat (der Standard):
curl -X POST 'https://api.normapi.de/v1/invoices?syntax=zugferd' \
  -H 'Authorization: Bearer nk_live_…' \
  -H 'Content-Type: application/json' \
  --data-binary @rechnung.json -o rechnung.pdf -D -

# Im Standardlayout von NormAPI:
curl -X POST 'https://api.normapi.de/v1/invoices?syntax=zugferd&letterhead=none' ...

Der Query-Parameter letterhead entscheidet je Aufruf:

Der Parameter wirkt bei Aufrufen mit API-Schlüssel; ohne Schlüssel gibt es kein Konto und keinen Briefkopf. Jeder andere Wert ist ein 400, das letterhead nennt, auch bei UBL und CII, wo der Wert sonst keine Wirkung hat. Im Aufruf mit Ihrem eigenen PDF wird er nicht gelesen: Dann ist Ihr PDF das Layout.

Zwei Antwort-Header sagen, was geschehen ist. Beide kommen nur bei ZUGFeRD auf unserer Seite und nur, wenn Ihr Konto einen Briefkopf hat; ohne Briefkopf und bei XML fehlen sie.

# Das PDF steht auf dem Briefkopf:
X-Normapi-Letterhead: lh_9f2c4e1a7b3d45f6a8c0e2b4d6f81357

# Standardlayout, mit Grund:
X-Normapi-Letterhead: none
X-Normapi-Letterhead-Skipped: requested

Trifft mehr als ein Grund zu, nennt der Header den ersten in dieser Reihenfolge. Mit einem Idempotency-Key nennt eine Wiederholung den Briefkopf, auf den der erste Aufruf gedruckt wurde; wurde der Briefkopf seither geändert, ist die Wiederholung eine andere Anfrage (422 idempotency-key-reused).

Platzhalter. Steht einer dieser Platzhalter als Text im Briefkopf, setzt NormAPI auf jeder Seite den Wert dafür ein, in Liberation Sans, in der Größe des Platzhalters und an dessen Stelle. Groß- und Kleinschreibung spielen keine Rolle.

Ohne Platzhalter steht auf Folgeseiten oben „Rechnung 2026-0042 · Seite 2 von 3“, bei einer Gutschrift „Gutschrift …“. Erkennt NormAPI die Platzhalter des Briefkopfs nicht, etwa weil die Schrift keine Unicode-Zuordnung hat, sagt es die Vorschau im Konto.

Das Adressfeld nach DIN 5008. NormAPI druckt den Empfänger in das Adressfeld und die Rechnungsangaben in den Informationsblock, jeweils an den Stellen der DIN 5008:2020, in Millimetern von der Oberkante der Seite. Der Text der Rechnung steht zwischen 25 und 190 mm vom linken Rand.

NormAPI erkennt die Form an den Faltmarken des Briefkopfs oder, ohne Marken, an der Rücksendezeile in der Zusatz- und Vermerkzone. Findet es weder noch, gilt der Briefkopf als ohne Fenster: Anschrift und Rechnungsangaben stehen dann direkt unter dem Briefkopf. Im Konto lassen sich Fensterform und Ränder ändern, und die Vorschau zeigt eine Beispielrechnung auf Ihrem Briefkopf mit dem Adressfeld als gestricheltem Kasten.

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 Rechnungen werden nicht gespeichert. Die Rechnung ist dieselbe; die internen Zeitstempel eines PDFs können abweichen.

Erzeugt Ihre Software Rechnungen für ihre eigenen Kunden — eine Buchhaltung, ein Shop-System, ein Portal —, dann nennen Sie bei jedem Aufruf den Kunden, für den er läuft: im Header X-Normapi-Customer, mit Ihrer eigenen Kennung für ihn. Es bleibt ein Konto mit einem Kontingent, aber NormAPI zählt jeden Kunden für sich. Im Konto unter Kunden sehen Sie je Monat, was jeder erzeugt hat, und können für jeden eine Obergrenze setzen.

curl -X POST https://api.normapi.de/v1/invoices \
  -H 'Authorization: Bearer nk_live_…' \
  -H 'X-Normapi-Customer: tenant-42' \
  -H 'Content-Type: application/json' \
  --data-binary @rechnung.json -o rechnung.xml

Ein Schlüssel je Kunde. Beim Anlegen lässt sich ein Schlüssel an einen Kunden binden. Jeder Aufruf damit zählt für diesen Kunden, auch ohne Header; nennt der Header einen anderen, antwortet die API mit 400 customer-mismatch. So kann ein Kunde, der seinen Schlüssel selbst in der Hand hat, nicht auf einen anderen buchen. Ein gebundener Schlüssel liest unter /v1/customers nur seinen eigenen Kunden und ändert keine Obergrenze (403 customer-bound-key).

Obergrenze je Kunde. Für einen Kunden lässt sich festlegen, wie viele Rechnungen er im Kalendermonat (UTC) höchstens erzeugt. Gezählt wird, was erzeugt wurde; Ablehnungen zählen nicht, und die Wiederholung eines gelungenen Aufrufs unter demselben Idempotency-Key wird auch an der Grenze ausgeliefert. Ist die Grenze erreicht, antwortet /v1/invoices für diesen Kunden mit 429 customer-quota-exceeded und einem Retry-After bis zum Monatsanfang. Prüfen und Auslesen bleiben frei, Ihre anderen Kunden arbeiten weiter. Darunter tragen gelungene Antworten X-Normapi-Customer-Used (in diesem Monat schon erzeugt) und X-Normapi-Customer-Limit.

{
  "type": "https://normapi.de/problems/customer-quota-exceeded",
  "title": "Monthly ceiling for this customer reached",
  "status": 429,
  "customer": "tenant-42",
  "used": 500,
  "limit": 500,
  "resetsAt": "2026-11-01T00:00:00Z"
}

Die Zahlen für Ihre Abrechnung gibt es auch über die API, mit demselben Schlüssel, ungezählt:

{
  "month": "2026-10",
  "customers": [
    { "customer": "tenant-42", "generated": 418, "refused": 3,
      "calls": { "generate": 421, "validate": 96 }, "monthlyInvoices": 500 },
    { "customer": "tenant-7", "generated": 97, "refused": 0,
      "calls": { "generate": 97 }, "monthlyInvoices": null }
  ],
  "withoutCustomer": { "generated": 12, "refused": 1,
    "calls": { "generate": 13, "validate": 40 } },
  "nextCursor": null
}

Ein Schlüssel ohne Konto bekommt hier 403 account-required, ein Aufruf ohne Schlüssel 401. Ist nextCursor nicht null, holt derselbe Aufruf mit cursor= diesem Wert die nächste Seite.

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 eine steuerliche Identifikation und in der XRechnung einen Kontakt, 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,
  "detail": "... Fields to correct: seller.vatId (BR-DE-16), seller.taxNumber (BR-DE-16).",
  "rulesetVersion": "v2026-08-31",
  "findings": [
    { "code": "BR-DE-16", "severity": "ERROR",
      "text": "[BR-DE-16] ... Umsatzsteueridentifikationsnummer ...",
      "fields": ["seller.vatId", "seller.taxNumber"],
      "explanation": { "meaning": "...", "cause": "...",
        "fix": "Tragen Sie mindestens eines der drei Elemente ein. ...",
        "url": "https://normapi.com/de/fehler#BR-DE-16" } }
  ]
}

• 30 Anfragen pro Minute je Client, zugleich das Burst-Budget. Darüber: 429 mit Retry-After.
• Ohne Schlüssel 10 erzeugte Rechnungen am Tag je Client (je IPv6-/64-Netz), bis Mitternacht deutscher Zeit. Darüber: 429 vom Typ daily-limit-reached mit Retry-After bis Mitternacht. Abgelehnte Daten (400, 422) zählen nicht, Prüfen und Auslesen haben kein Tageslimit, mit Schlüssel gilt das Kontingent des Tarifs.
• 5 MB je Dokument — echte E-Rechnungen sind Kilobytes.
• Begrenzte Parallelität beim Prüfen, Auslesen und Erzeugen von PDFs: 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 alle Endpunkte ab: validate(), parse() (ab 0.7.0) und generateInvoice(). Für den Briefkopf nimmt generateInvoicePdf() ab 0.9.0 die Option letterhead (auto oder none) und gibt letterhead und letterheadSkipped zurück.

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 alle Endpunkte, alle Statuscodes und die Feldstruktur — geeignet für Codegeneratoren, Mock-Server und den Import in jedes API-Werkzeug.

openapi.yamlPostman-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, und mit Konto der Playground: echte Aufrufe von Erzeugen, Prüfen und Auslesen, ohne Schlüssel und mit dem Aufruf als curl, TypeScript oder Python daneben.