Section navigation

API Reference

This page is the central reference for all fiskaly API endpoints, base URLs, authentication, and rate limits. Use it as your starting point for any product integration.

fiskaly provides two API architectures. See The Unified API for the full comparison.

Unified API

The Unified API uses shared base URLs and a common resource model across countries. Currently covers SIGN FR, SIGN IT, SIGN PT, SIGN SE, and SIGN CZ (preview).

	Details
TEST base URL	`https://test.api.fiskaly.com`
LIVE base URL	`https://live.api.fiskaly.com`
Required headers	`X-Api-Version` (date, e.g. `2026-05-04`), `X-Idempotency-Key` (UUID, on POST/PATCH), `X-Scope-Identifier` (resource scoping)
Resource IDs	Server-generated (use `X-Idempotency-Key` for idempotency)
Org management	Built into the product API (no separate Management API)

Product	Latest API Version	Docs
SIGN FR	2026-06-01	Docs
SIGN IT	2026-06-01	Docs
SIGN PT	2026-06-01	Docs
SIGN SE	2026-06-01	Current docs
SIGN CZ (preview)	2026-06-01	Docs

Specialized APIs

Each Specialized API has its own base URL and resource model, purpose-built for a specific country. Uses the Management API for organization management.

Product	API Version	Base URL (TEST)	Base URL (LIVE)	Docs
SIGN DE	v2	`https://kassensichv-middleware.fiskaly.com/api/v2/`	`https://kassensichv-middleware.fiskaly.com/api/v2/`	Interactive docs
SIGN AT	v1	`https://rksv.fiskaly.com/api/v1/`	`https://rksv.fiskaly.com/api/v1/`	Docs
SIGN ES	v1	`https://test.es.sign.fiskaly.com/api/v1/`	`https://live.es.sign.fiskaly.com/api/v1/`	Docs
Management	v0	`https://dashboard.fiskaly.com/api/v0/`	`https://dashboard.fiskaly.com/api/v0/`	Interactive docs

Complementary product APIs

These products work alongside SIGN and are not tied to a specific API architecture:

Product	Base URL (TEST)	Base URL (LIVE)	Docs
DSFinV-K (Germany)	`https://dsfinvk.fiskaly.com/api/v1/`	`https://dsfinvk.fiskaly.com/api/v1/`	Docs
SUBMIT DE (Germany)	`https://kassensichv.fiskaly.com/submission-api/v1/`	`https://kassensichv.fiskaly.com/submission-api/v1/`	Docs
SAFE	`https://test.safe.fiskaly.com/api/v1/`	`https://live.safe.fiskaly.com/api/v1/`	Docs
E-Invoice	`https://test.api.fiskaly.com/`	`https://live.api.fiskaly.com/`	Docs
eReceipt	`https://receipt.fiskaly.com/api/v1`	`https://receipt.fiskaly.com/api/v1`	Interactive docs

📘Endpoint availability

Some newer products have not yet published their base URLs publicly. Contact your account manager or sales@fiskaly.com for access to SIGN FR, SIGN ES, SIGN IT, SIGN PT, SIGN CZ, SAFE, and E-Invoice endpoints.

Authentication

All fiskaly APIs use the same Bearer token authentication pattern:

POST /auth with your api_key and api_secret
Receive an access_token (24h) and refresh_token (48h)
Include the token as Authorization: Bearer <token> in all subsequent requests
On 401, re-authenticate — do not retry with the same expired token

curl -X POST https://kassensichv-middleware.fiskaly.com/api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "api_secret": "YOUR_API_SECRET"
  }'

const response = await fetch(
  "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: "YOUR_API_KEY",
      api_secret: "YOUR_API_SECRET",
    }),
  }
);

const { access_token } = await response.json();

Then include the token in subsequent requests:

curl -X GET https://kassensichv-middleware.fiskaly.com/api/v2/tss \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

⚠️Keep your secrets safe

Never commit API secrets to source control or expose them in client-side code. Store them in environment variables or a secret manager.

💡Cache your token

The access token is valid for 24 hours. Re-authenticating on every request adds unnecessary latency. Cache the token and only refresh on 401.

Environments

Every product has a TEST (sandbox) and LIVE (production) environment:

	TEST (Sandbox)	LIVE (Production)
Purpose	Development and integration testing	Real transactions, audit-relevant data
Data	Ephemeral — safe to experiment, can be reset	Permanent — legally binding records
Billing	Free	Per contract
Default	All new organizations start here	Enable via HUB
Base URL prefix	Usually includes `middleware`	Direct product domain

⚠️TEST and LIVE are separate

Resources created in TEST do not exist in LIVE. When going to production, you must re-provision all resources (TSS, clients, signing units, etc.).

Rate limits

API rate limits vary by product and subscription plan. General guidelines:

Operation	Typical limit	Notes
Authentication	10 req/min	Cache tokens — do not auth per transaction
Transaction signing	200 req/min	Should never be a bottleneck for normal checkout
Export generation	Lower limits	Heavy operations — use async polling
Management operations	60 req/min	Organization/API key management

Rate limit headers

Every API response includes headers to help you manage your request budget:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets
`Retry-After`	Seconds to wait before retrying (only present on 429 responses)

If you hit a 429 Too Many Requests, back off with exponential delay. See the retry strategy for implementation guidance.

For enterprise rate limits or custom needs, contact your account manager.

Pagination

fiskaly APIs use two different pagination patterns depending on the API architecture.

Specialized APIs (SIGN DE, DSFinV-K)

Specialized APIs use offset-based pagination with limit and offset query parameters.

Parameter	Default	Maximum	Description
`limit`	100	1000	Number of items to return per page
`offset`	0	—	Number of items to skip from the start

The response includes count (total items), data (array of results), offset, and limit.

curl -X GET "https://kassensichv-middleware.fiskaly.com/api/v2/tss?limit=50&offset=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch(
  "https://kassensichv-middleware.fiskaly.com/api/v2/tss?limit=50&offset=100",
  {
    headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" },
  }
);

const { count, data, offset, limit } = await response.json();
// count: 250, data: [...50 items], offset: 100, limit: 50

Unified API (SIGN FR, SIGN IT, SIGN PT, SIGN SE, SIGN CZ)

The Unified API uses token-based pagination with limit and token query parameters.

Parameter	Default	Maximum	Description
`limit`	10	100	Number of items to return per page
`token`	—	—	Opaque cursor from a previous response’s `pagination.token`

The response includes results (array of resources) and, when more pages exist, a pagination object with token (cursor for the next page), next (ready-to-use URL of the next page), and limit. On the last page the pagination object is omitted entirely.

# First page
curl -X GET "https://test.api.fiskaly.com/organizations?limit=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Api-Version: 2026-06-01"

# Next page (use pagination.token from the previous response)
curl -X GET "https://test.api.fiskaly.com/organizations?limit=25&token=eyJpZCI6ImFiYzEyMyJ9" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Api-Version: 2026-06-01"

let token = null;
let allItems = [];

do {
  const url = new URL("https://test.api.fiskaly.com/organizations");
  url.searchParams.set("limit", "25");
  if (token) url.searchParams.set("token", token);

  const response = await fetch(url, {
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Version": "2026-06-01",
    },
  });

  const { results, pagination } = await response.json();
  allItems.push(...results);
  token = pagination?.token ?? null;
} while (token);

💡Choose the right pattern

Check which API architecture your product uses (Unified vs Specialized) to determine which pagination pattern to implement. See the tables at the top of this page.

SIGN APIs

SIGN DE v2

Interactive API Reference — full endpoint documentation with try-it-out

SIGN AT v1

Austrian RKSV — integration guide and endpoint reference

SIGN FR

French NF525 — signing, closures, archives, offline mode

SIGN ES v1

Spanish TicketBAI & Verifactu — XML generation, signing, submission

SIGN IT

Italian Registratore Telematico — cloud RT, receipt lottery

SIGN PT

Portuguese SAF-T (PT) — certified document signing with ATCUD

SIGN SE (TCS)

Swedish fiscalization — X.509, XML API, control codes

SIGN CZ (preview)

Czech EET 2.0 — real-time sales registration with POK confirmation

Quick links

DSFinV-K v1

German fiscal data export — cash point closings, audit exports

SUBMIT DE v1

ELSTER filing — taxpayer registration and declaration submission

SAFE

Compliant fiscal data archiving — automated or API-driven

E-Invoice

B2B e-invoicing via Peppol — Belgium live, more countries coming

eReceipt v1

Digital receipt generation — QR code, email, and link delivery

Management API v0

Organization, user, and API key management

SDKs and tools

Postman Collections

Pre-configured requests for SIGN DE — interactive API exploration

Quick Start

First signed transaction in under 5 minutes with code examples

Error Codes

Every error code, what causes it, and how to fix it

📘No client SDKs (yet)

fiskaly does not currently provide official client SDKs. All integrations are direct REST API calls. The API surface is small enough that a thin HTTP wrapper in your language of choice is typically sufficient. Check the Changelog for SDK announcements.