Fakturnia Developers Quickstart API reference Polski

Grow your tools with fakturnia.pl

Connect your app to our system and build exactly the solution you need. Issue invoices, manage clients and submit to KSeF through a clean REST API, while Fakturnia keeps every amount correct to the grosz.

Official developer documentation for the Fakturnia External REST API: authentication, invoicing, KSeF, webhooks, MCP and a machine-readable OpenAPI reference.

  • Easy interface
  • KSeF communication
  • Postman & CLI included
  • LLM / Agent friendly

Everything you need to ship

From your first token to production webhooks. The building blocks, fully documented.

Quickstart

Token, invoice and PDF in five minutes, with copy-paste cURL.

Authentication

OAuth 2.0 client credentials, bearer tokens and granular scopes.

Documents & amounts

Every document type and the exact, grosz-precise calculation rules.

Webhooks

React to events in real time and verify HMAC signatures.

Tools

Postman collection, curl CLI and a client generated from OpenAPI in any language.

For agents & bots

OpenAPI, llms.txt and Markdown, machine-readable by design.

MCP server

Issue invoices from ChatGPT, Claude, Gemini, Mistral Vibe, Perplexity or GitHub Copilot: OAuth 2.1, guided flow, user permissions.

How the integration works

Four steps from an empty account to an invoice accepted by KSeF. Try each of them in the sandbox first.

  1. Create an API application

    In Fakturnia open Inne → Integracje → REST API (the app is in Polish) and create an application. You get a client_id and a client_secret and choose the scopes the integration may use.

  2. Get a token

    Exchange the application credentials for a bearer token with the OAuth 2.0 client credentials flow. A token is valid for an hour: cache it and fetch a new one shortly before it expires.

  3. Issue a document

    A single POST /documents call creates the invoice together with the buyer. Fakturnia numbers it according to the account settings, calculates net, VAT and gross to the grosz and returns a document you can download as a PDF.

  4. Send it to KSeF and get the result

    Sending is a separate call, so you can check the document first. The KSeF result arrives through the document.sentToKSeF or document.ksefRejected webhook, or you poll the status endpoint.

Build your product on Fakturnia

The integration works on the same data as the web and mobile apps, so your system and your team in Fakturnia see the same documents.

Online shop

The invoice is issued as soon as an order is paid, goes to KSeF and comes back to the shop as a PDF for the customer. An idempotency key prevents a duplicate when the payment notice arrives twice.

CRM and sales tools

Keep clients and products in sync and fill in company details from the GUS register by tax ID (NIP) alone. Your sales team invoices from its own tool and accounting sees the invoice in Fakturnia.

Subscriptions and recurring services

Recurring rules issue invoices on schedule. Through the API you check the next run and pause a rule when a customer cancels.

Warehouse and logistics

Track stock in several warehouses, record receipts and issues (PZ, WZ, MM) and create a WZ for a sales invoice.

Purchase invoices from KSeF

Supplier invoices downloaded from KSeF reach your system through the document.ksefImported webhook, with the IDs you need to read their details.

AI assistant

Connect Fakturnia to ChatGPT, Claude or Gemini through the MCP server and issue invoices in a conversation, with a preview and a confirmation before anything is saved.

Frequently asked questions

Short answers, each with a link to the guide that covers the details.

Does the Fakturnia API support KSeF?

Yes. You send a document created through the API to KSeF with a separate call and get the result by webhook or from the status endpoint. The API also lets you check and test the KSeF connection of the account. Sending to KSeF

Can I test without legal consequences?

Yes. The sandbox is a separate copy of Fakturnia with its own accounts and API credentials. Invoices sent from it go to the test KSeF environment of the Ministry of Finance. Quickstart

Which plan do I need?

The REST API, webhooks and the MCP server are part of the MAX plan. A new account starts with a 14-day MAX trial, so you can begin right away. Authentication

How does the integration authenticate?

With the OAuth 2.0 client credentials flow. An API application gets only the scopes you choose, and you can also limit it to a list of IP addresses. Authentication

How many requests can I send?

Limits are counted per API application, not per IP address. Creating documents allows 30 requests per minute, and every response tells you in its headers how many are left. Rate limits

What if the connection drops while an invoice is being created?

Send the request with an Idempotency-Key header and retry it with the same key. Fakturnia returns the result of the first call instead of creating a second document. Idempotency

Is there an OpenAPI specification?

Yes. The full OpenAPI 3 specification can be downloaded in Polish and English, and you can generate a client in any language from it. A Postman collection and a curl-based CLI are included too. Tools