Fakturnia Developers Quickstart API reference Polski

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.

Base URL. The API has two environments. Endpoints in this reference are relative to the base URL of the environment you target:

  • Production — https://prod.api.fakturnia.pl/external/v1 (invoices are real and reach KSeF with legal effect).
  • Test environment (sandbox) — https://sandbox.api.fakturnia.pl/external/v1 (for learning and testing, with no legal effect).

0. Start in the test environment (sandbox)

Before you run anything against production, start in the sandbox. It is a full, isolated copy of Fakturnia where you can test your integration — including sending invoices to KSeF — with no legal or tax consequences whatsoever. This matters especially when your code is written (or co-written) by an LLM: confirm everything works in the sandbox first, then switch to production.

  1. Create a separate account in the test environment at https://sandbox.app.fakturnia.pl. Your production account does not work in the sandbox — they are two separate worlds with separate data.
  2. Generate sandbox API credentials (Inne → Integracje → REST API — the app UI is in Polish) on that test account. You will receive a client_id and client_secret that work only against https://sandbox.api.fakturnia.pl.
  3. Attach a test KSeF certificate. To test KSeF sending you need a certificate from the KSeF test environment, not the production one — a production certificate will not work against https://sandbox.api.fakturnia.pl. Log in to a test entity in the Ministry of Finance test portal https://ap-test.ksef.mf.gov.pl/web/, generate a certificate, and connect it to your sandbox account (Settings → KSeF).

Once your integration works in the sandbox, going live is just switching the base URL to https://prod.api.fakturnia.pl and using production API credentials and a production KSeF certificate.

1. Get your API credentials

The REST API is a MAX plan module: the account you create the API application on needs an active MAX plan (a new account starts with a 14-day MAX trial, so you can begin right away in the sandbox). Without the plan the token endpoint answers 403 access_denied.

Create an API application in your Fakturnia account (Inne → Integracje → REST API — the app UI is in Polish). You will receive a client_id and client_secret, and you select the scopes the application is allowed to use (for example documents:create, documents:read).

Treat the client_secret like a password. Never ship it in a browser, mobile app, or public repository. Working with an AI agent? Exclude the file holding your secrets from the agent's reach so it never ends up on third-party servers.

2. Exchange credentials for an access token

The API uses the OAuth 2.0 client-credentials flow. Exchange your client_id / client_secret for a short-lived bearer token (JWT).

curl -s https://prod.api.fakturnia.pl/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "client_5c62e069...",
    "client_secret": "secret_..."
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "documents:create documents:read clients:create"
}

Send the token as a Bearer header on every request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...

See Authentication for token caching, rotation and the full scope list.

3. Create your first invoice

You do not have to create the buyer first. Pass an inline buyer object and Fakturnia will find or create the contact for you. The seller is always taken from your company profile.

curl -s -X POST https://prod.api.fakturnia.pl/external/v1/documents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1f1d6e-0b2a-4a1e-9b1a-2a4e9b1a2a4e" \
  -d '{
    "documentType": "FakturaVAT",
    "issueDate": "2026-06-04",
    "buyer": {
      "nip": "5261040828",
      "name": "Acme Corp Sp. z o.o.",
      "street": "Marszałkowska 1",
      "postalCode": "00-001",
      "city": "Warszawa",
      "countryCode": "PL"
    },
    "products": [
      { "name": "Usługa programistyczna", "unitOfMeasure": "szt.", "quantity": 1, "netPrice": 100, "vatRate": 23 }
    ],
    "paymentMethodId": 6,
    "paymentStatusId": 1,
    "paymentDeadlineDate": "2026-06-18"
  }'

Every response is wrapped in a consistent envelope:

{
  "success": true,
  "data": {
    "document": {
      "id": "681a3b2c4d5e6f7a8b9c0d1e",
      "documentNumber": "FV/1/06/2026",
      "documentType": "FakturaVAT",
      "grossSum": 123,
      "netSum": 100,
      "vatSum": 23,
      "products": [
        { "name": "Usługa programistyczna", "quantity": 1, "netPrice": 100, "netValue": 100, "amountOfVat": 23, "grossValue": 123, "vatRate": 23 }
      ]
    }
  },
  "message": "DOCUMENT_CREATED",
  "executionTime": 142
}

You send prices, the API computes the math. Pass netPrice or grossPrice and vatRate; the backend computes netValue, amountOfVat and grossValue to the grosz. See Document types & amounts for the exact rules.

For more detail and tips see Creating documents: every request field, buyer and receiver resolution, annotations, and the logic for each document type.

4. Download the PDF

curl -s -L https://prod.api.fakturnia.pl/external/v1/documents/681a3b2c4d5e6f7a8b9c0d1e/download \
  -H "Authorization: Bearer $TOKEN" -o invoice.pdf

5. (Optional) Send it to KSeF

If your account has a configured KSeF connection, submit the invoice to Poland's National e‑Invoicing System:

curl -s -X POST https://prod.api.fakturnia.pl/external/v1/documents/681a3b2c4d5e6f7a8b9c0d1e/send-to-ksef \
  -H "Authorization: Bearer $TOKEN"

The call returns the ksefNumber right away when KSeF is fast, otherwise a processing status. For how to wait for the result correctly — the burst‑poll, the document.sentToKSeF webhook and the rate limit — see Sending to KSeF.

Next steps