OpenAPI specification

The whole contract is published as a single OpenAPI 3.1 document.

https://docs.fiskhub.com/openapi/fiskhub.v1.yaml

In the repository it is openapi/fiskhub.v1.yaml. That file is the source of truth: the copy served here is generated from it at build time, and CI lints it on every change, so the two cannot drift.

curl -sSO https://docs.fiskhub.com/openapi/fiskhub.v1.yaml

What is in it

• Every endpoint, with every parameter, header and status code.
• Request and response schemas matching the service’s own validation exactly — the same patterns for decimal amounts, the same OIB and ISU number formats, the same enums.
• A worked example for every response, success and error alike, including the no-JIR branch.
• The full error taxonomy, with the doc_url that resolves to each code’s page.
• Bearer authentication, and the two endpoints that need none.

Generating a client

# TypeScript types
npx openapi-typescript https://docs.fiskhub.com/openapi/fiskhub.v1.yaml \
  -o src/fiskhub.d.ts

# A typed fetch client
npx @hey-api/openapi-ts \
  -i https://docs.fiskhub.com/openapi/fiskhub.v1.yaml \
  -o src/fiskhub

# Anything else — Java, C#, Python, Go
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.fiskhub.com/openapi/fiskhub.v1.yaml \
  -g java -o ./client

Check what your generator does with jir

jir is ["string", "null"]. Generators differ in how they render a nullable field: some produce an optional property, some a nullable type, some drop the null entirely.

Whatever yours produces, make sure jir: null is a normal value in the resulting type and not an error, a thrown exception, or a missing field that crashes a deserialiser. That is the one place a generated client can quietly reintroduce the bug this documentation exists to prevent. Read handling the no-JIR response, then check the generated code.

Validating it yourself

npx @redocly/cli lint openapi/fiskhub.v1.yaml

The repository ships openapi/redocly.yaml, which extends the recommended ruleset. Two adjustments are deliberate and documented in that file: no-server-example.com is off, because the second server is the local mock and that is intentional; operation-4xx-response and no-invalid-media-type-examples are raised to errors, so every operation must document its failures and every example must actually validate against its schema.

Reading it as documentation

npx @redocly/cli preview-docs openapi/fiskhub.v1.yaml

The prose guides on this site cover the things a schema cannot: which branch is safe to retry, why Idempotency-Key is mandatory, what a null JIR means. Read fiscalizing a sale and handling the no-JIR response alongside the spec, not instead of it.

Stability

The document describes /v1, and /v1 never breaks. Changes to it are additive: new optional request fields, new response fields, new error codes, new endpoints. Anything breaking becomes a new document for /v2. See versioning.

Regenerate your client when the spec changes if you want the new capabilities; an existing generated client keeps working either way.