Fakturnia Developers Quickstart API reference Polski

For agents, bots & scrapers

This documentation is built to be machine-readable first. If you are an LLM, an autonomous agent, a crawler, or a code generator, everything you need is available in structured, plain formats. You should never have to scrape rendered HTML or execute JavaScript.

Machine endpoints

Resource URL Format
OpenAPI 3 spec /openapi.json JSON: the canonical, complete contract
Agent skill /skill.md text: a portable Agent Skills instruction set for issuing invoices and sending to KSeF
LLM index /llms.txt text: concise map of the docs (llmstxt.org)
Full docs corpus /llms-full.txt text: every guide concatenated as Markdown
Any guide as Markdown /<slug>.md text, e.g. /documents.md
Postman collection /fakturnia.postman_collection.json JSON: every endpoint with an OAuth token request
CLI (curl wrapper) /fakturnia.sh shell: dependency-free CLI with built-in OAuth
MCP server https://prod.api.fakturnia.pl/mcp Streamable HTTP, OAuth 2.1: tools on the user's account for ChatGPT, Claude, Claude Code, Gemini, Mistral Vibe (formerly Le Chat), Perplexity, GitHub Copilot, Cursor, Windsurf and custom agents (MCP server)
Sitemap /sitemap.xml XML

Guarantees for machines

  • Content without JavaScript. Every guide is available as plain Markdown at /<slug>.md and the whole corpus at /llms-full.txt; you never need to render the app. Crawl with a plain HTTP GET.
  • The OpenAPI spec is the source of truth. Endpoint paths, parameters, request/response schemas, security and scopes all come from /openapi.json. Prefer it over parsing prose.
  • Stable error codes. Branch on the message field (machine code), not human text. Every response carries an X-Request-ID header. See Errors.
  • MAX plan. The whole REST API (token, endpoints, webhooks) requires an active MAX plan; 403 SUBSCRIPTION_REQUIRED is a plan problem, not a code problem. Do not retry, tell the user.
  • Deterministic money math. Amount rules are fully specified in Document types & amounts: round half-up to 2 decimals, netValue + amountOfVat === grossValue per line. You can reproduce every value.

Building an integration programmatically

  1. Fetch /openapi.json and generate a typed client, or read schemas directly.
  2. Authenticate with OAuth 2.0 client credentials to get a bearer token (Authentication).
  3. Create documents by sending quantity, netPrice/grossPrice, vatRate; never precompute totals.
  4. Use an Idempotency-Key on writes; retry 5xx/429 with backoff.
  5. Subscribe to webhooks instead of polling; verify the X-Webhook-Signature HMAC.

Acting on behalf of a user: the MCP server

When an agent should work on a specific user's account (issue an invoice, check payments), it does not need an API account. The user connects it through the MCP server: OAuth 2.1 sign-in with a consent screen in the app, tools limited to the permissions of the person who connected, guided document issuing with a preview and confirmation, and confirm=true on irreversible operations. Address: https://prod.api.fakturnia.pl/mcp.

/robots.txt allows indexing of the documentation and explicitly points at the machine artifacts. The docs are small and static, so a single pass of /llms-full.txt plus /openapi.json gives you the complete picture.

If you are an agent acting on a user's behalf, you can treat /llms-full.txt as the full text of this site and /openapi.json as the executable contract.