Skip to main content
For the full error catalog and per-code retry guidance, see Errors.

​
Platform guarantees

OpenFiskal publishes these current platform targets for the fiscalization API:

​
Idempotency and concurrency per endpoint

The table below shows which endpoints require Idempotency-Key and If-Match (ETag). Endpoints not listed here (all GET, DELETE, and POST /registers/{id}/fiscalize) require neither header. PATCH endpoints for merchants, registers, and locations do not require If-Match or Idempotency-Key. These endpoints apply a last-writer-wins strategy — concurrency control is not enforced on resource metadata updates.

​
Idempotency rules

Send Idempotency-Key on every mutating operation request (POST /operations, POST /operations/{id}/complete, POST /operations/{id}/void). The following are Forward-looking platform rules. Clients should code against them, but server-side enforcement is not yet live (see Reserved codes):
  • retention window is at least 24 hours
  • uniqueness scope is endpoint plus merchant plus authenticated tenant
  • reusing a key with the same payload will return the original response
  • reusing a key with a different payload will return 409 idempotency_key_conflict

​
Concurrency rules

Operation mutation endpoints (POST /operations/{id}/complete, POST /operations/{id}/void) require If-Match with the latest operation ETag. Omit it and the API returns 428 precondition_required. Send a stale value and the API returns 412 precondition_failed; the expected and current versions are included in message (e.g. "Resource version mismatch. Expected 1, current is 2."). The If-Match header value must be a quoted positive integer (e.g. "1"); a malformed value returns 400 invalid_request. PATCH endpoints on merchants, registers, and locations accept updates without If-Match. These are metadata-only mutations where last-writer-wins is acceptable.

​
Request tracing

Every response includes an X-Request-Id header (e.g. req_a1b2c3d4e5f60718293a). Persist it in your logs and attach it to support cases.

​
Next steps