Fakturnia Developers Quickstart API reference Polski

Tools

The API is plain REST + JSON with a complete OpenAPI 3 specification, so you can work in any language and tool. Here is what we prepared: a Postman collection, a CLI for quick checks and a recipe for generating a typed client.

OpenAPI specification

The canonical API contract is /openapi.json (language versions: /openapi.pl.json, /openapi.en.json). It carries every endpoint, request and response schemas with examples, error codes, headers and the required scopes. The same specification powers the API reference and the interactive Swagger.

Generate a client in your language

Generate a client from OpenAPI, for example with openapi-generator:

# Python
openapi-generator generate \
  -i https://developers.fakturnia.pl/openapi.json \
  -g python -o ./fakturnia-python

# PHP, C#, Java, Go, TypeScript: change -g to php, csharp, java, go, typescript-fetch

You can also just use fetch / requests directly. See the Quickstart and the API reference for the exact data shapes. With a client of your own, keep three things from the guides in mind: cache the token (Authentication), send Idempotency-Key on writes (Idempotency) and retry 429 after Retry-After (Rate limits).

Postman collection

Import the ready-made Postman collection: every endpoint grouped by resource, with example request bodies taken straight from the specification. The collection includes an Authentication → get access token request whose test script stores the token in a collection variable, so every following request is authenticated automatically.

How to use it:

  1. Import https://developers.fakturnia.pl/fakturnia.postman_collection.json into Postman.
  2. Set the collection variables client_id and client_secret.
  3. Run Authentication → get access token once, then call any endpoint.
  4. To test against the sandbox, change the baseUrl and tokenUrl variables to their sandbox.api.fakturnia.pl counterparts.

Command line: the fakturnia CLI

A small, dependency-free shell wrapper around curl that fetches, caches and attaches the bearer token itself. Handy for quick checks and scripts.

curl -fsSL https://developers.fakturnia.pl/fakturnia.sh -o fakturnia && chmod +x fakturnia

export FAKTURNIA_CLIENT_ID=client_...
export FAKTURNIA_CLIENT_SECRET=secret_...
export FAKTURNIA_ENV=sandbox            # or: production

./fakturnia GET  /documents/
./fakturnia POST /documents/ '{"documentType":"FakturaVAT","issueDate":"2026-06-10","buyer":{"identifierType":"nip","nip":"5261040828","name":"Acme Corp Sp. z o.o.","street":"Marszałkowska 1","postalCode":"00-001","city":"Warszawa","countryCode":"PL"},"products":[{"name":"Usługa","unitOfMeasure":"szt.","quantity":1,"netPrice":100,"vatRate":23}],"paymentMethodId":6,"paymentStatusId":1,"paymentDeadlineDate":"2026-06-24"}'

It targets the sandbox by default; switch to production deliberately. POST/PUT/PATCH calls with a body get an automatic Idempotency-Key header.

For AI agents

/skill.md is a portable instruction file in the Agent Skills format and /llms-full.txt the whole documentation corpus in one file. Details on the For agents & bots page.

An assistant working on a user's account connects through the MCP server: ChatGPT, Claude and Claude Code, Gemini, Mistral Vibe (formerly Le Chat), Perplexity, GitHub Copilot, Cursor or Windsurf. It signs in with OAuth 2.1 instead of an API account, its tools are limited to the user's permissions and invoices go through a guided flow with a preview.