Getting Started - OpenFiskal Platform API

Overview

Exports are asynchronous. You create an export job, poll it until the artifact is ready, then download the file before the signed URL expires. The only export type currently available is DSFinV-K (Germany, KassenSichV). Additional types for other regimes will be added as those regimes are enabled.

Export types

Type	Description
`dsfinvk`	Germany (KassenSichV) — DSFinV-K archive containing the CSV files, `index.xml`, and GDPdU DTD mandated by the German tax authority

DSFinV-K exports are per-register: every request must specify register_id, and the register must be on the KassenSichV regime.

Requesting an export

Every export requires a type, a time range (from, to), and — for DSFinV-K — a register_id.

curl -X POST https://sandbox.api.openfiskal.com/v1/exports \
  -H "Authorization: Bearer of_test_deu_abc123..." \
  -H "X-OpenFiskal-Merchant: merchant_01HXYZ" \
  -H "Idempotency-Key: dsfinvk-2026-03" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "dsfinvk",
    "register_id": "reg_01HABC",
    "from": "2026-03-01T00:00:00Z",
    "to": "2026-03-31T23:59:59Z"
  }'

The resulting TAR archive contains the full DSFinV-K dataset: cashpointclosing.csv, transactions.csv, lines.csv, payment.csv, vat.csv, and the other mandated files alongside index.xml and the GDPdU DTD.

Synchronous validation at create time

POST /exports validates the request before enqueuing the job. The window is silently clamped to the register’s fiscalized lifetime (max(from, fiscalized_at) to min(to, decommissioned_at ?? now)) and the following checks run before the response is returned:

Status	Code	When
`400 bad_request`	`register_id_required_for_dsfinvk`	`register_id` is missing
`422 validation_error`	`validation_error`	Register is not on the KassenSichV regime
`422 validation_error`	`export_dsfinvk_no_closed_sessions`	Clamped window contains no closed sessions on the register
`422 validation_error`	`export_dsfinvk_build_pending`	A closed session in the window has no DSFinV-K cashpoint-closing yet — retry shortly

export_dsfinvk_build_pending is transient: the build pipeline runs asynchronously after session_close, so a fresh request can land before every closed session has been compiled. Retrying a few seconds later is the right response.

Polling and download

If validation passes, the job is enqueued and the response carries status: "pending":

{
  "id": "exp_01JDEF",
  "type": "dsfinvk",
  "status": "pending",
  "register_id": "reg_01HABC",
  "from": "2026-03-01T00:00:00Z",
  "to": "2026-03-31T23:59:59Z",
  "download_url": null,
  "error": null,
  "created_at": "2026-03-31T12:00:00Z",
  "completed_at": null
}

Poll GET /exports/{exportId} until status reaches completed:

{
  "id": "exp_01JDEF",
  "type": "dsfinvk",
  "status": "completed",
  "register_id": "reg_01HABC",
  "from": "2026-03-01T00:00:00Z",
  "to": "2026-03-31T23:59:59Z",
  "download_url": "https://storage.googleapis.com/...",
  "error": null,
  "created_at": "2026-03-31T12:00:00Z",
  "completed_at": "2026-03-31T12:00:42Z"
}

If the job fails, status is failed and the response carries an error object:

{
  "id": "exp_01JDEF",
  "type": "dsfinvk",
  "status": "failed",
  "error": {
    "message": "Build pipeline failed for session ses_01HZ.",
    "details": null
  },
  "completed_at": "2026-03-31T12:00:42Z"
}

Retention

download_url is a signed URL that expires 7 days after completed_at, matching the bucket lifecycle rule that deletes the artifact at the same point. Copy each artifact to your own durable storage before then. If the URL has expired, you can re-create the export for the same window.

Limitations today

DSFinV-K is the only export type currently available
There is no list endpoint; track the export IDs you create
AT (DEP7/RKSV) and IT (RT) export types will be added when those regimes ship

​Overview

​Export types

​Requesting an export

​Synchronous validation at create time

​Polling and download

​Retention

​Limitations today