AI & Agent Integration

fiskaly provides a comprehensive set of machine-readable endpoints and tooling designed for AI agents, coding assistants, and automated integration pipelines. This section documents how to discover, query, and integrate fiskaly APIs programmatically — without reading HTML documentation.

Architecture

AI agents interact with fiskaly through a layered discovery system:

┌─────────────────────────────────────────────────┐
│  Discovery Layer                                │
│  llms.txt → CLAUDE.md → ai-plugin.json          │
├─────────────────────────────────────────────────┤
│  Structured Data                                │
│  products.json → regulatory.json                │
│  human-interventions.json                       │
├─────────────────────────────────────────────────┤
│  API Specifications                             │
│  9 OpenAPI specs (JSON/YAML)                    │
├─────────────────────────────────────────────────┤
│  Interactive Tooling                            │
│  MCP Server (search, specs, products, errors)   │
└─────────────────────────────────────────────────┘

1. Discovery — llms.txt and ai-plugin.json tell agents what fiskaly is and where to find structured data.
2. Structured data — products.json provides machine-readable product metadata with base URLs, spec URLs, and documentation links.
3. API specs — 9 OpenAPI specifications cover every fiskaly product endpoint.
4. Interactive tooling — The MCP server lets agents search docs, retrieve specs, and look up error codes in real time.

Getting started as an AI agent

1. Fetch the discovery index

   Start with https://workspace.fiskaly.com/llms.txt for a plain-text index of all documentation and specs, or /CLAUDE.md for a structured integration guide.

2. Identify the right product

   Query https://workspace.fiskaly.com/products.json to find the product matching your target country. Each entry includes apiArchitecture, baseUrls, and specUrl.

3. Load the OpenAPI spec

   Fetch the spec URL from the product manifest (e.g., /specs/sign-de-v2.json) to get full endpoint definitions, request/response schemas, and authentication details.

4. Check for human-required steps

   Query /human-interventions.json to identify which steps need a human (account creation, API keys, go-live) and which are fully automatable.

💡Using Claude Code or Cursor?

Connect the fiskaly MCP server for interactive access to docs, specs, and error codes — no HTTP fetching needed. See the MCP Server guide.

What’s in this section

MCP Server

Set up and use the fiskaly-docs MCP server in Claude Code, Cursor, or any MCP client.

Machine-Readable Endpoints

All discovery and data endpoints with URLs, formats, and usage examples.

Agent Best Practices

Recommended integration flow, common anti-patterns, and per-country gotchas.

Human Interventions

Which actions are automatable and which require a human in the loop.