Health

Service health

GET /v1/health

FiskHub’s own liveness. No authentication required. Cheap, and safe to poll.

It says nothing about the Tax Administration — use /v1/health/fiscal for that.

curl -sS https://api.fiskhub.com/v1/health

{
  "status": "ok",
  "version": "1.0.0",
  "uptime_s": 148213,
  "checks": {
    "database": { "status": "ok", "latency_ms": 3 }
  },
  "checked_at": "2026-08-27T10:32:00+02:00"
}

status	HTTP	Meaning
ok	200	Everything is working.
degraded	200	Serving, but something is impaired.
down	503	A dependency the service cannot work without is unavailable.

Unauthenticated requests are limited per IP like everything else — see rate limits. A monitor polling every 10 seconds is nowhere near it.

Tax Administration reachability

GET /v1/health/fiscal

Sends the Tax Administration’s EchoRequest (specification §2.4) and reports whether a matching EchoResponse came back, and how long it took.

No authentication, no certificate, no tenant. Echo is an unsigned round trip that carries no invoice data, so answering “is the service reachable” touches nobody’s signing key. That is what makes it usable as a probe from an orchestrator or an uptime monitor that holds no credential.

curl -sS https://api.fiskhub.com/v1/health/fiscal

{
  "reachable": true,
  "latency_ms": 412,
  "endpoint": "https://cis.porezna-uprava.hr:8449/FiskalizacijaService",
  "mode": "live",
  "checked_at": "2026-08-27T10:32:00+02:00",
  "detail": null
}

Unreachable:

{
  "reachable": false,
  "latency_ms": 4002,
  "endpoint": "https://cis.porezna-uprava.hr:8449/FiskalizacijaService",
  "mode": "live",
  "checked_at": "2026-08-27T10:32:00+02:00",
  "detail": "Echo timed out after 4000 ms"
}

Field	Notes
reachable	Whether a matching EchoResponse came back. The answer — read this, not the HTTP status.
latency_ms	Round trip in milliseconds; the elapsed time up to the failure when unreachable.
endpoint	The endpoint that was probed.
mode	test or live — which endpoint this deployment is configured against. There is no way to ask for the other one; that is decided by configuration, not by a request.
checked_at	When the probe ran. Results are cached for about 15 seconds, so this may be slightly in the past.
detail	Why it failed, or null. Human-readable, not a contract.

The HTTP status is always 200, in both cases. The probe ran and this is its result; reporting a third party’s outage as our own 503 would only get our container restarted, which fixes nothing.

The result is cached for about 15 seconds and concurrent callers share one in-flight probe. That is deliberate: without it, a dashboard left open and a few uptime monitors would turn this endpoint into a small denial-of-service against the one service we cannot afford to annoy.

A probe, not a gate

A green result does not guarantee that the next POST /v1/invoices will succeed. Echo says the endpoint answered a few seconds ago. It says nothing about your certificate, your ISU number, the contents of your sale, or whether the service is still answering right now.

A red result does not excuse blocking a sale. Fiscalize anyway: the ZKI is computed locally, the receipt is compliant, and the retry sweep catches up when the service returns. Invariant 4 stands regardless of what this endpoint reports — see handling the no-JIR response.

This endpoint is not on the fiscal decision path in either direction. Do not call it before each sale; you would add a round trip to every transaction to obtain information you must not act on. Call it when invoices start coming back as retrying and you want to know whether the problem is theirs or yours.

The TEST maintenance windows

The Tax Administration’s TEST service is unavailable on weekdays from 16:00 to 17:00 and on Sundays from 08:00 to 12:00, Europe/Zagreb. During a window the probe simply reports reachable: false — it is a genuine outage of the TEST endpoint, and nothing distinguishes a scheduled one from an unscheduled one over the wire.

CI has to tolerate this. It is also a free rehearsal of the no-JIR branch: during a window, fh_test_ fiscalization returns exactly the response your integration most needs to handle correctly.