> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openfiskal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Offline and recovery

> How to operate within the documented offline boundaries, issue provisional receipts, and recover safely.

## 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.

## Legal and operational boundaries

* 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](/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

* [Transaction lifecycle](/pos-operation-ingestion)
* [Hosted Receipts API](/hosted-receipts-api)