Quick Start with Postman

For a quick first demo, you may use Postman. We prepared a Postman collection that allows you to step through the most important functions of this API.

1. Download Postman

   Download the Postman application.

2. Create credentials

   Create an API Key and API Secret via fiskaly HUB.

3. Download Environment

   Download the fiskaly SAFE flex Postman environment JSON-based configuration file: Download Postman Environment

4. Download Collection

   Download the fiskaly SAFE flex Postman collection JSON-based configuration file: Download Postman Collection

5. Import

   Start Postman and import the downloaded Postman environment and collection files.

6. Configure

   Select the fiskaly SAFE flex environment and fill in apiKey, apiSecret, and scopeId to match your credentials. apiBaseUrl is pre-filled and points at the test environment.

7. Create a token

   Run tokens (management) → Create a token first. It stores the returned access token as the token environment variable, which every other request uses for authentication.

8. Upload a file

   For the files → Upload a file request, select the Body tab, ensure archive_file_request is listed above the file field, and click Select Files to choose the PDF you want to upload.

9. Run

   Work through the folders in the order listed below, running the requests within each folder one by one.

Important: Run Requests Step by Step

📘Note

We recommend executing each request manually in the listed order rather than using the Postman Collection Runner. Some requests depend on values saved from previous responses, and the Upload a file request requires a PDF file to be selected manually — which the Runner cannot handle automatically.

Collection Structure

The collection is organized into folders. Run them in this order the first time through:

Folder	Purpose
tokens (management)	Creates the access token. Run this first — everything else needs it.
configuration	Sets and reads the country configuration for your archive.
annotations	Defines and reads the annotation schemas used when archiving.
files	Uploads, retrieves, and downloads archived files.
search	Creates a search, checks its status, and fetches the result.
export	Creates an export, checks its status, and downloads it.
logs	Retrieves the audit log.

📘Note

The access token expires. If requests start failing with an authentication error, re-run tokens (management) → Create a token to refresh the token environment variable.

Within search and export, the requests are sequential: create the search or export, retrieve its status, then fetch the result or download the data. Each step reuses the searchId or exportId saved by the create request.

One-Time Setup Requests

The following requests only need to be executed once per environment. Re-running them will create new annotation schemas with a different random suffix, which is valid but not necessary.

• configuration → Create a configuration — Sets the country configuration for your archive. Run this once before anything else.
• annotations → Create a string annotation — Defines the annotation schema for store information. The annotation name is generated with a random suffix (e.g. receipt_store_info_47832) and saved automatically as an environment variable.
• annotations → Create mix property annotation — Defines the annotation schema for receipt metadata (cashier, amount, payment methods, date). The annotation name is generated with a random suffix (e.g. receipt_metadata_62135) and saved automatically as an environment variable.

Once these are set up, you can run all other requests (Upload, Search, Export, etc.) repeatedly.

Uploading a File

The files → Upload a file request uses multipart/form-data with two fields:

• archive_file_request — a JSON object containing the file metadata and annotation values (pre-filled automatically via a pre-request script).
• file — the actual PDF file to archive.

💡Tip

The file field cannot be pre-filled automatically. Before sending the request, select the Body tab in Postman, make sure archive_file_request is listed above the file field, click Select Files next to the file field, and choose the PDF you want to upload.

The custom_identifier, file name, and annotation names are resolved automatically on each request via pre-request scripts.