ELSTER-Prüfung per API: amtlich prüfen mit ERiC, ohne zu übermitteln

Was die Prüfung tut – und was nicht

Die API baut den Datensatz so, wie ihn der Versand bauen würde, und lässt ihn von ERiC plausibilisieren – mit Testmerker, ohne Übermittlung und ohne Transferticket. Am Übermittlungsstand der Meldung ändert sich nichts. ERiC ist die Programmbibliothek, die die Steuerverwaltung Softwareherstellern zur Einbindung bereitstellt; sie prüft Steuerdaten auf Plausibilität, bevor sie verschlüsselt an die Annahmeserver gehen.

Neben dem ERiC-Ergebnis meldet die API, was die Software selbst weiß: offene Fragen des Vordrucks, einen gesperrten Zeitraum, einen ungeklärten früheren Versand, ein fehlendes ELSTER-Zertifikat der Gesellschaft oder die Sandbox. Diese Punkte stehen als hindernisse in der Antwort. Fehlt das Zertifikat, bricht die API die Prüfung nicht ab, sondern nennt das Hindernis zertifikat_fehlt.

Die Anfrage je Art

art ist Pflicht, dazu kommt genau eine Kennung. Ein Feld, das nicht zur Art passt, lehnt die API mit 400 invalid_request ab und nennt das erwartete.

Beispiel mit curl

Prüfung der Voranmeldung für September 2026; der Schlüssel kommt aus der Umgebungsvariable JAB_API_KEY:

curl -s -X POST \
  "https://api.jahresabschluss.io/functions/v1/bookkeeping-api/v1/tax/check" \
  -H "Authorization: Bearer $JAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"art": "ustva", "period": "2026-09"}'

Über MCP heißt derselbe Aufruf check_tax_filing mit den Argumenten art und period. Das Werkzeug ist nicht als nur lesend gekennzeichnet, weil jede Prüfung gezählt und protokolliert wird, und es braucht das Recht „Schreiben“ – obwohl nichts gesendet wird. Das vollständige Schema steht ohne Schlüssel unter /functions/v1/bookkeeping-api/openapi.json.

Die Antwort lesen

Gekürzt; die Texte stammen aus ERiC bzw. aus der Software:

{
  "art": "ustva",
  "zeitraum": "2026-09",
  "valid": false,
  "eric": {
    "valid": false,
    "field_errors": [
      { "feld": "…", "text": "…", "regel_id": "…", "schwere": "…" }
    ],
    "hinweise": []
  },
  "hindernisse": [
    { "code": "eric_fehler", "text": "…" },
    { "code": "zusatzangaben_offen", "text": "…" }
  ],
  "manifest": { "art": "ustva", "zeitraum": "2026-09", "kennzahlen": { "…": "…" } },
  "manifest_sha256": "…"
}

• valid: true, wenn ERiC den Datensatz annimmt; false bei Beanstandungen; null, wenn ERiC kein Ergebnis geliefert hat. Bei Voranmeldung und E-Bilanz steht dann amtliche_pruefung_fehlt in hindernisse, bei den übrigen Arten antwortet die API mit einem Fehlercode und app_seite.
• eric.field_errors: je Beanstandung Feld, Text, Regel-Kennung und Schwere, höchstens 100 Einträge.
• eric.hinweise: Hinweise von ERiC, die für sich keine Beanstandung sind.
• hindernisse: Liste aus code und text. Ist sie leer, spricht aus Sicht der Software nichts gegen eine Übermittlung.
• manifest und manifest_sha256: die geprüften Werte und ihr SHA-256-Prüfwert. Für die Freigabe eingefroren werden sie erst mit POST /v1/tax/operations.

Fehlermeldungen verstehen und beheben

ERiC-Beanstandungen beziehen sich auf Felder des amtlichen Datensatzes. Ein Agent kann sie übersetzen: Er liest das Feld, sucht mit get_vat_return die Buchungen hinter der betroffenen Kennzahl oder mit get_entity die Stammdaten, schlägt eine Korrektur vor und prüft nach Ihrer Bestätigung erneut. Ziel ist eine richtige Meldung, nicht eine, die nur die Prüfung besteht. Die HTTP-Fehler der Route:

• 400 invalid_request: art fehlt, falsches Kennungsfeld oder falsches Format.
• 403: Dem Schlüssel fehlt das Recht „Schreiben“; ein Schlüssel einer Gesellschaft nur mit dem Steuer-Modul bekommt außerhalb der Steuer-Routen nur_steuer_routen.
• 404 not_found: Meldung oder E-Bilanz gehört nicht zu dieser Gesellschaft oder existiert nicht.
• 409 fiscal_year_ambiguous (kein eindeutiges Geschäftsjahr), stand_geaendert (Meldung während der Prüfung geändert), nicht_erzeugt (E-Bilanz-Datei fehlt).
• 422 api_berichtigung_nur_in_app bzw. api_zerlegung_nur_in_app: Berichtigungen und Gewerbesteuer mit Zerlegung prüfen und übermitteln Sie in der App.
• 429 rate_limited: mehr als 30 Prüfungen, Vorbereitungen und Entwürfe in einer Stunde mit diesem Schlüssel.
• 503 limits_unavailable oder steuer_dienst_nicht_bereit: Es wurde nichts ausgeführt; später erneut versuchen.

Grenzen und Rechte

• Recht „Schreiben“ für POST /v1/tax/check; „Lesen“ genügt für GET /v1/tax/filings, GET /v1/tax/deadlines und GET /v1/tax/operations/{id}.
• 30 Prüfungen, Vorbereitungen und Entwürfe zusammen je Stunde und Schlüssel; gezählt werden abgeschlossene Aufrufe.
• 120 Anfragen pro Minute je Schlüssel über alle Routen; darüber 429 mit Retry-After.
• Ein Schlüssel gilt für genau eine Gesellschaft und höchstens 366 Tage; je Gesellschaft sind bis zu 10 aktive Schlüssel möglich.
• In der Sandbox wird geprüft wie in der echten Gesellschaft; die Antwort trägt dort das Hindernis sandbox.
• Lohnsteuer-Anmeldung, Kapitalertragsteuer-Anmeldung, Feststellungs- und Einkommensteuererklärung prüft die Steuer-API nicht.

Vom Prüfen zur Übermittlung

Ist die Prüfung sauber, friert POST /v1/tax/operations (prepare_tax_filing) Werte und Prüfwert für 30 Minuten ein; POST /v1/tax/operations/{id}/approval-link liefert den Freigabe-Link, sieben Tage gültig. Übermittelt wird in der App, mit Zwei-Faktor-Bestätigung und der PIN des Nutzers; GET /v1/tax/operations/{id} meldet danach Status und Transferticket.

Das OpenAPI-Schema beschreibt zusätzlich eine Übermittlungsroute. Sie verlangt ein eigenes Recht, das derzeit nicht vergeben wird; ohne dieses Recht antwortet sie mit 403. Planen Sie Ihre Anbindung deshalb mit dem Freigabe-Link.

Häufige Fragen

Gibt es eine API, mit der sich Steuermeldungen amtlich prüfen lassen, ohne sie zu senden?

Ja: POST /v1/tax/check der REST-API von jahresabschluss.io bzw. das MCP-Werkzeug check_tax_filing. Es prüft mit ERiC und übermittelt nichts.

Wird bei der Prüfung etwas an das Finanzamt übermittelt?

Nein. Die Prüfung läuft ohne Versand und ohne Transferticket, auch in der Sandbox; der Übermittlungsstand der Meldung bleibt unverändert.

Brauche ich für die Prüfung ein ELSTER-Zertifikat?

Die API bricht die Prüfung ohne Zertifikat nicht ab; sie meldet zertifikat_fehlt als Hindernis. Für die spätere Übermittlung in der App braucht es ein Zertifikat – das der Gesellschaft oder in der App auch das Ihrer Kanzlei.

Welche Steuerarten lassen sich prüfen?

Umsatzsteuer-Voranmeldung, Zusammenfassende Meldung, Dauerfristverlängerung, Sondervorauszahlung, Umsatzsteuer-Jahreserklärung, E-Bilanz, Körperschaftsteuer, Gewerbesteuer und Anlage EÜR.

Wie oft darf ich prüfen?

Bis zu 30 Prüfungen, Vorbereitungen und Entwürfe zusammen je Stunde und Schlüssel, bei insgesamt höchstens 120 Anfragen pro Minute. Darüber antwortet die API mit 429.

Was bedeutet valid: null?

ERiC hat kein Ergebnis geliefert, etwa weil eine Voraussetzung fehlt. Bei Voranmeldung und E-Bilanz steht der Grund im Hindernis amtliche_pruefung_fehlt.