Integrationsleitfaden

Dieser Leitfaden behandelt die Elmar REST API: Endpunkte, Payload-Struktur, Fehlerbehandlung und empfohlene Betriebsmuster.

Interaktive Docs: Wenn Elmar REST läuft, besuchen Sie /docs/swagger-ui für die vollständige OpenAPI-3.1-Spezifikation mit Try-it-out-Funktionalität.

API-Überblick

Alle Steuerformular-Übermittlungen folgen demselben Muster:

1. POST eines TaxDeclaration-Payloads (JSON oder XML) an den formularspezifischen Endpunkt
2. taxOfficeId als Pfadparameter angeben
3. Optional ?dryRun=true setzen, um ohne Übermittlung zu validieren
4. Eine ResultDetail-Antwort mit dem ERiC-Ergebnis erhalten, einschließlich etwaiger Fehler

---

Steuerformular-Endpunkte

Alle Endpunkte akzeptieren application/json oder application/xml und liefern denselben Content-Type zurück.

Methode	Pfad	Steuerformular
POST	/api/ustva/2026/{taxOfficeId}	UStVA 2026 (Umsatzsteuer-Voranmeldung)
POST	/api/ustva/2025/{taxOfficeId}	UStVA 2025 (Umsatzsteuer-Voranmeldung)
POST	/api/ust/2025/{taxOfficeId}	USt 2025 (Umsatzsteuer-Jahreserklärung)
POST	/api/gewst/2024/{taxOfficeId}	GewSt 2024 (Gewerbesteuer)
POST	/api/kst/2024/{taxOfficeId}	KSt 2024 (Körperschaftsteuer)
POST	/api/fse/kapg/202301/{taxOfficeId}	FSE KapG 2023 (Feststellungserklärung)

Pfadparameter

Parameter	Typ	Beschreibung
taxOfficeId	string	Die BUFA-Nummer des Zielfinanzamts

Query-Parameter

Parameter	Typ	Standard	Beschreibung
dryRun	boolean	false	Bei true wird der Payload über ERiC validiert, ohne ihn zu übermitteln

---

Request-Payload

Jeder Übermittlungsendpunkt akzeptiert einen TaxDeclaration-Wrapper mit Header und formularspezifischen Daten:

{
  "Header": {
    "RefId": "ihre-tracking-id-max-32ch",
    "PdfUploadUri": "https://ihr-server/upload/pfad.pdf",
    "UploadHeaders": {}
  },
  "Data": {
    // Formularspezifische Felder (entspricht der ELSTER-XSD-Struktur)
  }
}

Header-Felder

Feld	Pflicht	Beschreibung
RefId	ja	Ihr Transfer-Ticket / Tracking-ID (max. 32 Zeichen)
PdfUploadUri	nein	Falls gesetzt, lädt Elmar das ERiC-generierte PDF nach erfolgreicher Übermittlung an diese URI hoch
UploadHeaders	nein	Zusätzliche HTTP-Header für den PDF-Upload

Data-Felder

Das Data-Objekt enthält die formularspezifischen Nutzdaten-Felder, entsprechend der Struktur in der zugehörigen ELSTER-XSD. Die genauen Felder variieren je nach Formulartyp und Jahr.

Bei JSON-Übermittlung entsprechen die Feldnamen 1:1 dem JAXB-generierten Java-Modell (das die XSD-Elementnamen widerspiegelt). Nutzen Sie die OpenAPI-Docs (/docs/swagger-ui) für das exakte Schema pro Endpunkt.

---

Finanzamt-Endpunkte

Methode	Pfad	Beschreibung
GET	/api/tax-offices/states	Alle Bundesländer auflisten
GET	/api/tax-offices/offices?stateCodeOrTesting={code}	Finanzämter eines Bundeslandes auflisten (oder "testing" für Testfinanzämter)
GET	/api/tax-offices/offices/{bufaNr}	Bestimmtes Finanzamt nach BUFA-Nummer abrufen
GET	/api/tax-offices/unified-tax-no?stateCodeOrBufaNr={id}&stateTaxNo={no}	Landessteuernummer in bundeseinheitliche Steuernummer umrechnen

---

Info-Endpunkte

Methode	Pfad	Beschreibung
GET	/api/info/eric-version	ERiC-Bibliotheksversion
GET	/api/info/eric-certificate-properties	Eigenschaften des geladenen Zertifikats
GET	/api/info/eric-manufacturer-id	Konfigurierte Hersteller-ID
GET	/api/info/testmode-enabled	Ob der Testmodus aktiv ist

---

Fehlerbehandlung

Elmar fügt keine eigene Validierungsschicht hinzu. Fehler von ERiC werden transparent in der Antwort zurückgegeben.

• Erfolgreiche Übermittlung: HTTP 201 Created mit ResultDetail inkl. Transfer-Ticket
• Validierungs- / ERiC-Fehler: HTTP 422 Unprocessable Entity mit ResultDetail inkl. ERiC-Fehlerdetails
• Die Antwort enthält auch aktuelle ERiC-Log-Ausgaben zum Debugging

---

Empfohlene Betriebsmuster

Work-Queue für Spitzenlasten

Elmar serialisiert den ERiC-Zugriff intern. Für Spitzenübermittlungstage (z.B. monatliche UStVA-Fristen) schalten Sie Elmar hinter eine Work-Queue, damit Ihre Anwendung responsiv bleibt:

Ihre App → Message-Queue → Worker → Elmar REST → ELSTER

Eine Instanz pro Zertifikat

Jeder Elmar-Container wird mit einem einzelnen ELSTER-Zertifikat konfiguriert. Wenn Sie mehrere Organisationen bedienen, betreiben Sie mehrere Instanzen.

Health-Checking

Nutzen Sie die Info-Endpunkte (z.B. /api/info/eric-version) als leichtgewichtigen Health-Check für Ihren Orchestrator.

PDF-Handling

Wenn Sie eine PdfUploadUri im Request-Header angeben, lädt Elmar das ERiC-generierte PDF-Antwortdokument nach erfolgreicher Übermittlung an diese URI hoch. Ohne URI wird das PDF lokal im Container gespeichert.