Integration Planning

This page is for product managers and technical leads planning a fiskaly integration. It covers effort estimates, team requirements, product dependencies, compliance milestones, and a rollout timeline template.

💡For developers

If you are looking to write code, start with the Quick Start instead.

Step 1: Choose your API architecture

fiskaly provides two API architectures. Your choice depends on which countries you need:

If you need…	Use…	Why
Only Germany, Austria, or Spain	Specialized API for that country	Purpose-built, deepest country-specific support
Only France or Italy	Unified API	Multi-country architecture — adding the other is ~1 week
France + Italy (or + Sweden)	Unified API	Integrate once, expand by changing payload schema
Germany + France/Italy	Both	Specialized API for DE + Unified API for FR/IT. Same auth pattern, different resource models.
3+ countries including FR/IT	Start with Unified API	Then add Specialized APIs for DE/AT/ES as needed

See The Unified API for the full architecture comparison, resource model, and terminology mapping.

Step 2: Determine your product scope

Which fiskaly products you need depends on where you operate and what regulations apply. Use this decision tree:

Do you operate POS systems in any of these countries?

• Germany -> SIGN DE + DSFinV-K + SUBMIT DE (all three mandatory)
• Austria -> SIGN AT
• France -> SIGN FR (NF525 certification required)
• Spain -> SIGN ES (TicketBAI or Verifactu, depending on region)
• Italy -> SIGN IT
• Sweden -> SIGN SE (InfraSec TCS)
• Belgium -> E-Invoice (B2B only, via Peppol)

Do you need compliant long-term archival? -> Add SAFE or SAFE flex

Do you want to replace paper receipts? -> Add eReceipt (optional, any EU country)

Germany is the most complex

Germany requires three products working together. Here is how they relate:

SIGN DE (transaction signing)
  |
  +--> DSFinV-K (fiscal export generation, references SIGN DE data)
  |
  +--> SUBMIT DE (ELSTER filing, references SIGN DE clients and TSS)
  |
  +--> SAFE (optional archival of exports)

For other countries, SIGN is typically the only mandatory integration.

Step 3: Estimate integration effort

These are typical timelines for a team of 1-2 backend developers with POS domain experience. Your actual timeline depends on your POS architecture, release cadence, and testing requirements.

Specialized APIs (SIGN DE, SIGN AT, SIGN ES)

Product	First integration	From SIGN DE	Notes
SIGN DE	4-8 weeks	—	TSS provisioning, transaction signing, receipt QR code, error handling
SIGN AT	3-5 weeks	1-2 weeks	Closest to SIGN DE. SCU instead of TSS, FinanzOnline registration.
SIGN ES	5-7 weeks	2-4 weeks	Certificate management, 6 invoice types, real-time submission

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

Product	First Unified API country	Each additional	From SIGN DE	Notes
SIGN FR	4-6 weeks	—	1-3 weeks	NF525 certification adds 4-8 weeks separately
SIGN IT	4-6 weeks	—	1-3 weeks	Receipt lottery, connection loss handling
FR + IT	4-6 weeks (first)	~1 week (second)	—	Same resource model — only payload and Taxpayer fiscalization differ
SIGN SE	2-4 weeks	—	—	Currently InfraSec TCS (XML, X.509); Unified API coming

Complementary products

Product	Duration	Notes
DSFinV-K	2-4 weeks	Germany only. Map POS data model to DSFinV-K taxonomy.
SUBMIT DE	1-2 weeks	Germany only. Simple if SIGN DE is already integrated.
SAFE	1 week (SAFE) / 2 weeks (flex)	SAFE auto-links to SIGN; SAFE flex requires manual upload logic.
E-Invoice	2-4 weeks	Belgium live; others coming. Separate from SIGN.
eReceipt	1-2 weeks	Country-independent. Mostly frontend work (QR display).

Typical Germany-only timeline

Week 1-2:  Account setup, sandbox access, SIGN DE auth + TSS provisioning
Week 3-5:  Transaction signing, receipt generation, error handling
Week 5-6:  DSFinV-K mapping and export generation
Week 6-7:  SUBMIT DE integration
Week 7-8:  End-to-end testing in sandbox
Week 8-9:  Go-live preparation, LIVE environment provisioning
Week 9-10: Production rollout, monitoring

Total: ~10 weeks from kickoff to production for Germany (SIGN DE + DSFinV-K + SUBMIT DE).

Multi-country rollout timeline

If you are expanding from an existing SIGN DE integration:

Week 1:    Review target country documentation, identify payload differences
Week 2:    Implement country-specific adapter, sandbox testing
Week 3:    QA, receipt compliance validation, go-live

Total: ~3 weeks per additional country (AT, FR, IT, ES).

Step 4: Plan your team

Role	Responsibility	When needed
Backend developer (1-2)	API integration, transaction signing, error handling, retry logic	Full integration period
Frontend developer (0-1)	Receipt rendering, QR code display, eReceipt UI	After backend signing works
QA engineer (1)	End-to-end testing, compliance validation, edge cases (timeouts, offline)	Weeks 5+
Product manager	Scope decisions, compliance requirements gathering, go-live checklist	Throughout
DevOps / Infra (0-1)	Secret management, monitoring, alerting for signing failures	Go-live prep

Step 5: Understand the compliance checklist

Before going live in any country, verify these items:

Universal checklist (all countries)

• API credentials stored in a secret manager (not in source code)
• Token caching implemented (do not re-authenticate per transaction)
• Retry logic with exponential backoff for 5xx and timeout errors
• Signing timeout configured (3-5 seconds) and does not block checkout
• Receipt includes all mandatory fields for the target country
• Error handling covers TSS unavailability (see error handling guide)
• TEST environment integration tests pass
• LIVE environment provisioned via HUB
• Monitoring/alerting set up for signing failures and latency

Germany-specific checklist

• TSS created, Admin PIN set, and TSS initialized
• Client created for each POS terminal
• Receipt includes KassenSichV QR code (see receipt data)
• QR code validates correctly (see QR code validation)
• DSFinV-K export generates and validates
• SUBMIT DE declaration files successfully with ELSTER
• Admin logout after provisioning

France-specific checklist

• NF525 certification process started with fiskaly support
• Period closures implemented (daily, monthly, yearly)
• Archive generation automated
• Offline replay mode tested

Italy-specific checklist

• Receipt lottery (Lotteria degli Scontrini) fields included
• Connection loss handling tested
• Taxpayer location and system states managed correctly

Step 6: Go-live preparation

1. Complete sandbox testing

   Run your full test suite against the TEST environment. Verify all transaction types, error scenarios, and export generation.

2. Request LIVE access

   Switch your organization to the LIVE environment via HUB. Contact your account manager if you need assistance.

3. Provision LIVE resources

   Resources from TEST do not carry over. Re-run your provisioning flow (TSS creation, client registration) in the LIVE environment.

4. Staged rollout

   Start with a single location or terminal. Monitor signing latency, error rates, and receipt compliance for 1-2 weeks before expanding.

5. Set up monitoring

   Track: signing success rate, average signing latency, 401 error rate (token refresh issues), and 5xx error rate (service issues). Alert on signing failure rate > 1%.

⚠️TEST and LIVE are completely separate

TSS, clients, transactions, and exports created in TEST do not exist in LIVE. Your go-live deployment must include a provisioning step.

Key links for PMs

Product overview

What each product does and when you need it

Country Coverage (E-Invoice)

When new country modules become available

SAFE vs SAFE flex

Which archival option fits your use case

Error codes reference

Every error your team will encounter and how to resolve it

HUB (dashboard)

Manage organizations, API keys, and compliance exports without code

Changelog

API changes, new features, and deprecation notices