Skip to main content

​
Overview

If OpenFiskal is temporarily unreachable, your backend should queue the fiscalization calls it would normally send, then replay them when connectivity returns. Offline handling is a compliance-controlled workflow. You should treat it as an exception path with audit logging, operator guidance, and manual remediation.
  • Only use offline processing where the configured country capability allows it
  • Keep a durable audit trail of the local action, operator, and device
  • Treat locally rendered receipts as provisional until OpenFiskal confirms completion
  • Never rewrite timestamps, totals, or tender composition during replay

​
What to queue

Queue the exact mutation requests you would have sent online:
  • POST /operations
  • POST /operations/{operationId}/complete
  • POST /operations/{operationId}/void
Each queued entry should include:
  • the original request body
  • the original Idempotency-Key
  • the last known If-Match value when the request is a mutation
  • the business timestamp from your POS domain model
  • the local operator and terminal context

​
Replay rules

  1. Replay queued requests in the original business order.
  2. Reuse the original idempotency key on retry.
  3. Do not recalculate payload values during replay.
  4. Re-read the operation if replay receives 412 precondition_failed.
  5. Stop on the first unresolved network or semantic error and resolve that item before continuing.

​
When OpenFiskal is up but the underlying signing service is down

A separate failure mode is OpenFiskal being reachable while its upstream signing service (e.g. the Fiskaly TSS for KassenSichV registers) is unavailable. Most fiscal events are signed inline and a signing failure surfaces as 422 validation_error on POST /operations/{id}/complete — your normal retry-after-recovery path applies. The exception is session_cash_count: signing the counted-vs-expected variance is best-effort. If the upstream signing service is unreachable at count time, the API still returns 2xx, the session transitions to counted, and the variance is recomputed locally. The signature is filled in later when the signing service recovers. From the integrator’s point of view this is invisible — the session’s customer-facing Z-Bon flow is unaffected.

​
Provisional receipts

If you complete checkout in your POS before OpenFiskal is reachable again, treat any locally produced receipt as provisional with a “Signature unavailable” message. After the queued completion succeeds, the authoritative fiscal payload is the fiscal_information block on the completion response. A dedicated Hosted Receipts API is planned but not yet available; in the current release, integrators render receipts themselves from fiscal_information.

​
Failure recovery

Escalate to manual remediation when:
  • the replay queue cannot restore ordering
  • a payload now fails regime validation
  • the operation was already completed through another channel
  • a provisional receipt was issued but no final completion can be obtained inside the required timeline

​
Implementation checklist

  • persist queued mutations durably
  • retain idempotency keys across retries
  • preserve operation ordering
  • preserve the latest operation ETag
  • surface replay failures for manual resolution
  • fetch the hosted receipt only after the completion call succeeds

​
Next steps