# Fakturnia Developers

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

- Base URL: https://prod.api.fakturnia.pl/external/v1
- OpenAPI: https://developers.fakturnia.pl/openapi.json
- Full text: https://developers.fakturnia.pl/llms-full.txt
- Agent skill: https://developers.fakturnia.pl/skill.md
- Postman collection: https://developers.fakturnia.pl/fakturnia.postman_collection.json
- CLI (curl wrapper): https://developers.fakturnia.pl/fakturnia.sh
- MCP server (ChatGPT, Claude, Claude Code): https://prod.api.fakturnia.pl/mcp (docs: https://developers.fakturnia.pl/docs/mcp)

## Documentation
- [Quickstart](https://developers.fakturnia.pl/docs/quickstart): Issue your first invoice through the Fakturnia API in about five minutes. You will obtain an access token, create a buyer-and-invoice in one call, and download the PDF.
- [Authentication](https://developers.fakturnia.pl/docs/authentication): The Fakturnia API authenticates with **OAuth 2.0 client credentials**. Your application exchanges a `client_id` / `client_secret` pair for a short-lived **bearer token** (JWT), then sends that token on every request.
- [Document types & amounts](https://developers.fakturnia.pl/docs/documents): This page is the one to read before you build invoicing. It explains **which document types exist**, **what you send**, and exactly **how amounts are computed**, down to the grosz. Getting the money math right is the whole game, so the rules are spelled out precisely.
- [Creating documents](https://developers.fakturnia.pl/docs/creating-documents): This is the complete guide to `POST /external/v1/documents`, the single endpoint you need to issue an invoice, proforma, advance, settlement, correction or order. It covers every request field, how transaction parties are resolved, the per-type logic and the KSeF annotations. For the money math and the full type map see [Document types & amounts](/docs/documents); here we focus on **how to build a correct request**.
- [Sending invoices to KSeF](https://developers.fakturnia.pl/docs/ksef): Issuing an invoice and sending it to KSeF (Poland's National e‑Invoicing System) are **two separate steps**. You first create the document, then send it. There is no single call that creates and sends at once, and that is deliberate: it lets you create, review or validate a document before it becomes a legal e‑invoice.
- [Correcting documents](https://developers.fakturnia.pl/docs/correcting-documents): You issue corrections with the same endpoint as any other document, `POST /external/v1/documents`, using one of three types:
- [KSeF connection](https://developers.fakturnia.pl/docs/ksef-connection): Before you send your first invoice to KSeF, the account needs a configured connection: the certificate Fakturnia uses to authenticate with KSeF on behalf of your company. This page covers managing that connection through the API. Sending invoices is covered in [Sending to KSeF](/docs/ksef).
- [Order references](https://developers.fakturnia.pl/docs/external-references): If you integrate Fakturnia with a shop or another sales system, you can link a document to the order in your system. The link is visible in the app and lets you tell documents issued by the integration apart from those issued manually.
- [Clients](https://developers.fakturnia.pl/docs/clients): A client is the buyer or receiver on your documents. The API exposes full CRUD under `/clients`, and when [creating documents](/docs/creating-documents) you can reference a client by `id` instead of sending their details every time.
- [Products](https://developers.fakturnia.pl/docs/products): Products and services form the catalog of line items you use when issuing documents. The API exposes full CRUD under `/products`.
- [Settings](https://developers.fakturnia.pl/docs/settings): The `/settings` endpoint reads and updates the account settings that affect documents issued through the API: the date format and document numbering.
- [Warehouse](https://developers.fakturnia.pl/docs/warehouse): The warehouse module tracks goods with a movement ledger: a product's stock level is the sum of its receipts and issues. Through the API you manage warehouses, issue warehouse documents (WZ, PZ, PW, RW, MM), record stock adjustments, fetch a stock report for any day and issue WZ (goods issue) documents for sales invoices.
- [Employees and permissions](https://developers.fakturnia.pl/docs/employees): An employee account is a separate login identity (own email and password) that works on the owner account's data. The owner grants the employee permissions from a closed registry, e.g. read-only access to documents or full invoicing. Through the API you can automate creating such accounts, e.g. when onboarding a new employee in your HR system.
- [Recurring documents](https://developers.fakturnia.pl/docs/recurring-rules): A recurring rule is a document template paired with a schedule. Once configured, it issues invoices on its own (`AUTO` mode), prepares drafts for approval (`DRAFT`) or just sends a reminder to issue one (`REMINDER`). Through the API you can read rule state and generation history, and pause or resume a rule, for example when a customer cancels their subscription in your system.
- [Email accounts](https://developers.fakturnia.pl/docs/email-accounts): A Fakturnia account can e-mail documents from the owner's own mailbox instead of the system address. Mailboxes are connected in the app (Other → Email accounts): SMTP with a password, or Gmail and Outlook through OAuth. Through the API you can check which mailboxes are connected and in what state. That is all: **connecting, verifying and editing happen only in the app**, because they need a password or an OAuth consent that an integration should not hold.
- [History and activity](https://developers.fakturnia.pl/docs/activity): Everything that happens on the account is journaled: who issued a document, when it went out by e-mail, whether KSeF accepted it, who marked the payment, which movements passed through the warehouse, when an employee logged in. Through the API you read those journals in four ways, depending on the question.
- [Company lookup by NIP](https://developers.fakturnia.pl/docs/company-lookup): The `/company/nip-lookup` endpoint fetches Polish company data from the GUS registry. Use it to auto-fill [client](/docs/clients) details or the buyer when [creating a document](/docs/creating-documents), instead of asking the user to retype everything.
- [Errors](https://developers.fakturnia.pl/docs/errors): The API uses standard HTTP status codes and a **consistent error envelope**. Every error carries a stable, machine-readable `message` (the error code) and, where it matters, details in `errors`.
- [Dictionaries](https://developers.fakturnia.pl/docs/dictionaries): All the enum values you need when creating documents are returned by one endpoint:
- [Rate limits](https://developers.fakturnia.pl/docs/rate-limits): The API applies rate limits to keep things fast and fair. Limits are counted per application (API account), identified by the token, not per IP address. They are tightest on expensive endpoints:
- [PDF rendering queue](https://developers.fakturnia.pl/docs/pdf-download-queue): `GET /documents/{id}/download` renders the invoice PDF on the server. Rendering is CPU-bound, so it runs in a small pool of background workers with a bounded queue. Under heavy load the queue can fill up. When that happens the API does **not** make you wait or time out. It responds immediately with `429` and the error code `WAIT_PDF_QUEUE`, telling you to retry shortly.
- [Pagination](https://developers.fakturnia.pl/docs/pagination): List endpoints (`GET /documents`, `GET /clients`, `GET /products`, `GET /recurring-rules`, `GET /recurring-rules/{id}/history`, `GET /webhooks/{id}/deliveries`, `GET /documents/{id}/history`, `GET /warehouse/movements`) are paginated with query parameters:
- [Idempotency](https://developers.fakturnia.pl/docs/idempotency): Network calls fail in ambiguous ways: a request times out, but did the document get created? Idempotency keys let you **safely retry** mutating requests without creating duplicates.
- [Webhooks](https://developers.fakturnia.pl/docs/webhooks): Webhooks push events to your server the moment something happens, so you do not have to poll the API. Register an HTTPS endpoint, pick the events, verify the signature on every delivery and answer quickly with `2xx`. Like the whole REST API, webhooks require the MAX plan: events are delivered only while the account has an active MAX plan and at least one active API application.
- [Tools](https://developers.fakturnia.pl/docs/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.
- [For agents, bots & scrapers](https://developers.fakturnia.pl/docs/agents): 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.
- [MCP server: invoices from ChatGPT, Claude, Gemini and other AI assistants](https://developers.fakturnia.pl/docs/mcp): Fakturnia ships an **MCP (Model Context Protocol)** server so an AI assistant can work directly on a user's account: issue invoices, check payments, look up contractors, read stock levels and send documents to KSeF. It works with ChatGPT, Claude and Claude Code, Gemini, Mistral Vibe (formerly Le Chat), Perplexity, GitHub Copilot, Cursor and Windsurf, as well as other MCP clients and your own agent. The user connects the assistant with a single sign-in (OAuth 2.1), and every data change goes through a preview and a confirmation in the conversation.
- [Changelog](https://developers.fakturnia.pl/docs/changelog): The API is versioned in the path (`/external/v1`). Breaking changes ship under a new major version; additive changes (new fields, new endpoints, new optional parameters) roll out within `v1`. Treat unknown response fields as forward-compatible: ignore what you don't recognise.

## Reference
- [API reference](https://developers.fakturnia.pl/api)
- [OpenAPI specification](https://developers.fakturnia.pl/openapi.json)