Integration guide

This guide covers the Elmar REST API: endpoints, payload structure, error handling, and recommended operational patterns.

Interactive docs: When running Elmar REST, visit /docs/swagger-ui for the full OpenAPI 3.1 specification with try-it-out functionality.

API overview

All tax form submissions follow the same pattern:

1. POST a TaxDeclaration payload (JSON or XML) to the form-specific endpoint
2. Include the target taxOfficeId as a path parameter
3. Optionally set ?dryRun=true to validate without submitting
4. Receive a ResultDetail response with ERiC's result, including any errors

---

Tax form endpoints

All endpoints accept application/json or application/xml and return the same content type.

Method	Path	Tax form
POST	/api/ustva/2026/{taxOfficeId}	UStVA 2026 (VAT advance return)
POST	/api/ustva/2025/{taxOfficeId}	UStVA 2025 (VAT advance return)
POST	/api/ust/2025/{taxOfficeId}	USt 2025 (annual VAT return)
POST	/api/gewst/2024/{taxOfficeId}	GewSt 2024 (trade tax)
POST	/api/kst/2024/{taxOfficeId}	KSt 2024 (corporate income tax)
POST	/api/fse/kapg/202301/{taxOfficeId}	FSE KapG 2023 (determination)

Path parameters

Parameter	Type	Description
taxOfficeId	string	The BUFA number of the target tax office

Query parameters

Parameter	Type	Default	Description
dryRun	boolean	false	When true, validates the payload via ERiC without submitting

---

Request payload

Every submission endpoint accepts a TaxDeclaration wrapper containing a header and form-specific data:

{
  "Header": {
    "RefId": "your-tracking-id-max-32ch",
    "PdfUploadUri": "https://your-server/upload/path.pdf",
    "UploadHeaders": {}
  },
  "Data": {
    // Form-specific fields (matches the ELSTER XSD structure)
  }
}

Header fields

Field	Required	Description
RefId	yes	Your transfer ticket / tracking ID (max 32 characters)
PdfUploadUri	no	If set, Elmar uploads the ERiC-generated PDF to this URI after successful submission
UploadHeaders	no	Additional HTTP headers to include when uploading the PDF

Data fields

The Data object contains the form-specific Nutzdaten fields, matching the structure defined in the corresponding ELSTER XSD. The exact fields vary per form type and year.

When sending JSON, the field names map 1:1 to the JAXB-generated Java model (which mirrors the XSD element names). Use the OpenAPI docs (/docs/swagger-ui) for the exact schema per endpoint.

---

Tax office endpoints

Method	Path	Description
GET	/api/tax-offices/states	List all tax office states
GET	/api/tax-offices/offices?stateCodeOrTesting={code}	List tax offices for a state (or "testing" for test offices)
GET	/api/tax-offices/offices/{bufaNr}	Get a specific tax office by BUFA number
GET	/api/tax-offices/unified-tax-no?stateCodeOrBufaNr={id}&stateTaxNo={no}	Convert state tax number to unified country tax number

---

Info endpoints

Method	Path	Description
GET	/api/info/eric-version	ERiC library version
GET	/api/info/eric-certificate-properties	Loaded certificate properties
GET	/api/info/eric-manufacturer-id	Configured manufacturer ID
GET	/api/info/testmode-enabled	Whether test mode is active

---

Error handling

Elmar does not add its own validation layer. Errors from ERiC are returned transparently in the response.

• Successful submission: HTTP 201 Created with ResultDetail containing the transfer ticket
• Validation / ERiC errors: HTTP 422 Unprocessable Entity with ResultDetail containing ERiC error details
• The response also includes recent ERiC log output for debugging

---

Recommended operational patterns

Work queue for peak loads

Elmar serializes access to ERiC internally. For peak submission days (e.g., monthly UStVA deadlines), place Elmar behind a work queue so your application remains responsive:

Your app → Message queue → Worker → Elmar REST → ELSTER

One instance per certificate

Each Elmar container is configured with a single ELSTER certificate. If you serve multiple organizations, run multiple instances.

Health checking

Use the info endpoints (e.g., /api/info/eric-version) as a lightweight health check for your orchestrator.

PDF handling

When you provide a PdfUploadUri in the request header, Elmar uploads the ERiC-generated PDF response document to that URI after a successful submission. If no URI is provided, the PDF is saved locally inside the container.