Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dev.openfiskal.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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
  • PATCH /operations/{operationId}/complete
  • PATCH /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.

​
Provisional receipts

If you complete checkout in your POS before OpenFiskal is reachable again, treat any locally produced receipt as provisional. After the queued completion succeeds, the authoritative fiscal payload is the fiscal_information block on the completion response. Reprint or re-render using those verbatim fields — regime validation depends on them (TSE signature, QR data, document number). 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