E-Rechnungen per API prüfen

1. API-Schlüssel holen

Kostenloses Coretool-Konto auf coretool.de anlegen, anmelden und einen Schlüssel erzeugen. Der Schlüssel beginnt mit ct_live_ und wird nur einmal angezeigt; wir speichern ihn ausschließlich als Hash.

# Anmelden (liefert ein Login-Token)
curl -s https://api.coretool.de/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"du@example.de","password":"…"}'

# Mit dem Login-Token einen API-Schlüssel anlegen
curl -s https://api.coretool.de/v1/keys \
  -H "Authorization: Bearer <LOGIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"mein-tool"}'

2. Rechnung prüfen

POST /v1/validate mit der Datei im multipart-Feld file. Schlüssel im Header X-API-Key oder als Authorization: Bearer ct_live_…. Mit ?report=true gibt es zusätzlich die einzelnen Prüfschritte (XSD, Schematron).

curl -s https://api.coretool.de/v1/validate \
  -H "X-API-Key: $CORETOOL_API_KEY" \
  -F "file=@rechnung.xml"

# ZUGFeRD-PDF mit Prüfbericht
curl -s "https://api.coretool.de/v1/validate?report=true" \
  -H "Authorization: Bearer $CORETOOL_API_KEY" \
  -F "file=@rechnung.pdf"

import os, requests

with open("rechnung.xml", "rb") as f:
    r = requests.post(
        "https://api.coretool.de/v1/validate",
        headers={"X-API-Key": os.environ["CORETOOL_API_KEY"]},
        files={"file": ("rechnung.xml", f)},
        timeout=60,
    )

if r.status_code == 402:
    print("Kontingent aufgebraucht:", r.json()["error"]["pricing"])
else:
    r.raise_for_status()
    ergebnis = r.json()
    print(ergebnis["valid"], ergebnis["format"]["profile"])
    for fehler in ergebnis["errors"]:
        print(fehler["code"], "-", fehler["title"], "->", fehler["hint"])

// Node.js 18+ oder Browser-Backend (Schlüssel nie im Frontend ausliefern)
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("rechnung.xml")]), "rechnung.xml");

const res = await fetch("https://api.coretool.de/v1/validate", {
  method: "POST",
  headers: { "X-API-Key": process.env.CORETOOL_API_KEY },
  body: form,
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
console.log(data.valid, data.result, data.errors.map(e => e.code));

3. Antwort

valid ist true, wenn keine Fehler vorliegen (Warnungen sind erlaubt). result: valid, valid_with_warnings, invalid oder not_an_einvoice.

{
  "api_version": "1",
  "valid": false,
  "result": "invalid",
  "summary": "…",
  "input": { "type": "xml", "embedded_xml": null },
  "format": {
    "syntax": "UBL Invoice",
    "profile": "XRechnung",
    "specification_id": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
    "validation_scenario": "EN16931 XRechnung (UBL Invoice)"
  },
  "errors": [{
    "code": "BR-DE-15",
    "severity": "error",
    "message": "[BR-DE-15] Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.",
    "title": "…", "explanation": "…", "hint": "…",
    "field": "BT-10", "xpath": "…", "count": 1
  }],
  "warnings": [],
  "notes": [],
  "usage": { "plan": "free", "free_calls_total": 3, "free_calls_used": 2, "free_calls_remaining": 1 },
  "request_id": "req_…"
}

Leitweg-ID prüfen

POST /v1/leitweg/pruefen prüft eine Leitweg-ID nach den KoSIT-Regeln (Aufbau aus Grob- und Feinadressierung, Prüfziffer nach MOD 97-10). Body ist JSON mit dem Feld leitweg_id. Die Antwort ist flach und enthält Meldungen auf Deutsch (fehler, hinweise) und Englisch (fehler_en, hinweise_en) sowie maschinenlesbare Codes (fehler_code, fehler_codes). Eine ungültige ID ist ein normales Ergebnis: HTTP 200 mit "gueltig": false. Jede Prüfung zählt zum Kontingent (siehe unten); ein leeres Feld wird nicht berechnet.

curl -s https://api.coretool.de/v1/leitweg/pruefen \
  -H "X-API-Key: $CORETOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"leitweg_id":"04011000-1234512345-07"}'

{
  "gueltig": false,
  "ergebnis": "ungueltig",
  "pruefziffer_ok": false,
  "leitweg_id": "04011000-1234512345-07",
  "grobadressierung": "04011000",
  "feinadressierung": "1234512345",
  "pruefziffer": "07",
  "pruefziffer_soll": "06",
  "land": "Bremen",
  "fehler": "Die Prüfziffer stimmt nicht: Am Ende müsste „06“ stehen statt „07“. …",
  "fehler_en": "Check digits do not match: the ID should end with \"06\" instead of \"07\". …",
  "fehler_code": "check_digits_mismatch",
  "fehler_codes": ["check_digits_mismatch"],
  "anzahl_fehler": 1,
  "hinweise": "…", "hinweise_en": "…", "hinweis_codes": ["fine_starts_with_digit"],
  "berechnet": true,
  "kontingent_rest": 1,
  "usage": { "plan": "free", "free_calls_total": 3, "free_calls_used": 2, "free_calls_remaining": 1 },
  "api_version": "1",
  "request_id": "req_…"
}

ergebnis ist gueltig, ungueltig oder leer. pruefziffer_ok ist null, wenn die Prüfziffer wegen eines falschen Aufbaus nicht prüfbar ist. Eine gültige ID liefert "gueltig": true und leere Felder fehler/fehler_en.

Schlüssel testen

GET /v1/auth/test (oder POST) prüft, ob ein Schlüssel gültig ist. Der Aufruf verbraucht kein Kontingent und zählt nur zur Bremse. 200 = gültig, 401 = ungültig oder widerrufen.

curl -s https://api.coretool.de/v1/auth/test -H "X-API-Key: $CORETOOL_API_KEY"

{
  "gueltig": true,
  "valid": true,
  "key_id": "key_…",
  "usage": { "plan": "free", "free_calls_total": 3, "free_calls_used": 0, "free_calls_remaining": 3 },
  "nachricht": "API-Schlüssel gültig.",
  "message": "API key is valid."
}

Fehlercodes

Fehler kommen als {"error": {"code": "…", "message": "…", "message_en": "…"}} (Ausnahme 422, siehe Tabelle).

Weitere Endpunkte

Grenzen und Datenschutz

• Höchstens 5 MB je Datei, bis zu 5 aktive Schlüssel je Konto.
• Bremse je Schlüssel über alle Endpunkte: 60 Aufrufe pro Minute und 1.000 Aufrufe pro Tag, danach HTTP 429 mit Retry-After. Die Rechnungsprüfung (/v1/validate) ist zusätzlich auf 30 pro Minute begrenzt.
• Die Rechnung wird nur für die Prüfung im Arbeitsspeicher verarbeitet und danach verworfen.
• Gespeichert werden nur Zähl- und Protokolldaten: Zeitpunkt, Schlüssel-ID, Ergebnisklasse, Format, Dateigröße, Dauer. Kein Dateiname, kein Inhalt; bei der Leitweg-Prüfung wird die Leitweg-ID nicht protokolliert. Details in der Datenschutzerklärung.
• Das Prüfergebnis ist eine technische Prüfung gegen EN 16931/XRechnung, keine steuerliche Beratung.

Kontingent

Zum Start: 3 Prüfungen kostenlos je Konto, ohne Zahlungsdaten. Rechnungs- und Leitweg-Prüfungen zählen gemeinsam. Bezahlpakete folgen. Für mehr Prüfungen schreib uns bis dahin an support@coretool.de.

Demnächst

E-Rechnungen als lesbare Ansicht ausgeben, E-Rechnungen erzeugen und PDF in E-Rechnung umwandeln – außerdem Bausteine für n8n, Zapier und Make.