Dokumentacja API Faktuj

Faktuj API pozwala programistycznie generowac faktury VAT w formacie PDF. API jest calkowicie darmowe i otwarte — nie wymaga kluczy API ani uwierzytelniania. Wystarczy wyslac zapytanie HTTP z danymi faktury, a w odpowiedzi otrzymasz gotowy dokument PDF lub podglad danych w formacie JSON.

Bazowy URL: https://faktuj.pl/api/v1

Uwierzytelnianie

Brak uwierzytelniania. API jest darmowe i otwarte dla wszystkich. Wystarczy wysylac zapytania HTTP do ponizszych endpointow — bez klucza API, bez rejestracji, bez ograniczen dostepu.

POST /invoice/generate

POST /api/v1/invoice/generate

Generuje fakture VAT i zwraca ja jako plik PDF (application/pdf). Dane faktury przekazujesz w ciele zapytania jako JSON.

Naglowki zapytania

Naglowek	Wartosc	Wymagany
`Content-Type`	`application/json`	wymagany

Cialo zapytania

Pelny schemat obiektu InvoiceRequest znajduje sie w sekcji Schemat zapytania ponizej.

Przykladowe zapytanie

          
          
          
          cURL
        
curl -X POST "https://faktuj.pl/api/v1/invoice/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "numer": "FV/2026/02/001",
    "dataWystawienia": "2026-02-15",
    "dataSprzedazy": "2026-02-15",
    "miejsceWystawienia": "Warszawa",
    "terminPlatnosci": "2026-03-01",
    "metodaPlatnosci": "przelew",
    "sprzedawca": {
      "nazwa": "Kowalski Consulting Sp. z o.o.",
      "nip": "5213456789",
      "adres": "ul. Marszalkowska 10",
      "kodPocztowy": "00-624",
      "miasto": "Warszawa",
      "numerKonta": "PL 61 1090 1014 0000 0712 1981 2874"
    },
    "nabywca": {
      "nazwa": "Nowak Software S.A.",
      "nip": "7891234560",
      "adres": "ul. Krakowska 5",
      "kodPocztowy": "31-066",
      "miasto": "Krakow"
    },
    "pozycje": [
      {
        "nazwa": "Uslugi programistyczne",
        "ilosc": 160,
        "jednostka": "godz.",
        "cenaNetto": 150.00,
        "stawkaVat": 23
      },
      {
        "nazwa": "Hosting aplikacji",
        "ilosc": 1,
        "jednostka": "usl.",
        "cenaNetto": 500.00,
        "stawkaVat": 23
      }
    ],
    "uwagi": "Platnosc przelewem w terminie 14 dni."
  }' \
  --output faktura.pdf

Odpowiedz

W przypadku sukcesu serwer zwraca plik PDF z naglowkami:

Naglowek	Wartosc
`Content-Type`	`application/pdf`
`Content-Disposition`	`attachment; filename="FV-2026-02-001.pdf"`

POST /invoice/preview

POST /api/v1/invoice/preview

Zwraca podglad danych faktury w formacie JSON — w tym obliczone kwoty netto, VAT i brutto dla kazdej pozycji oraz podsumowanie. Przydatne do weryfikacji danych przed wygenerowaniem PDF.

Przykladowe zapytanie

          
          
          
          cURL
        
curl -X POST "https://faktuj.pl/api/v1/invoice/preview" \
  -H "Content-Type: application/json" \
  -d '{
    "numer": "FV/2026/02/001",
    "dataWystawienia": "2026-02-15",
    "dataSprzedazy": "2026-02-15",
    "sprzedawca": {
      "nazwa": "Kowalski Consulting Sp. z o.o.",
      "nip": "5213456789"
    },
    "nabywca": {
      "nazwa": "Nowak Software S.A.",
      "nip": "7891234560"
    },
    "pozycje": [
      {
        "nazwa": "Uslugi programistyczne",
        "ilosc": 160,
        "jednostka": "godz.",
        "cenaNetto": 150.00,
        "stawkaVat": 23
      }
    ]
  }'

Przykladowa odpowiedz

          
          
          
          200 OK
        
{
  "status": "success",
  "data": {
    "numer": "FV/2026/02/001",
    "dataWystawienia": "2026-02-15",
    "dataSprzedazy": "2026-02-15",
    "sprzedawca": {
      "nazwa": "Kowalski Consulting Sp. z o.o.",
      "nip": "5213456789"
    },
    "nabywca": {
      "nazwa": "Nowak Software S.A.",
      "nip": "7891234560"
    },
    "pozycje": [
      {
        "nazwa": "Uslugi programistyczne",
        "ilosc": 160,
        "jednostka": "godz.",
        "cenaNetto": 150.00,
        "stawkaVat": 23,
        "wartoscNetto": 24000.00,
        "kwotaVat": 5520.00,
        "wartoscBrutto": 29520.00
      }
    ],
    "podsumowanie": {
      "razemNetto": 24000.00,
      "razemVat": 5520.00,
      "razemBrutto": 29520.00,
      "vatWedlugStawek": {
        "23": { "netto": 24000.00, "vat": 5520.00, "brutto": 29520.00 }
      }
    }
  }
}

Schemat zapytania (InvoiceRequest)

Ponizej opisana jest struktura obiektu JSON przesylanego w ciele zapytania do obu endpointow.

Obiekt glowny

Pole	Typ	Wymagane	Opis
`numer`	string	wymagane	Numer faktury, np. "FV/2026/02/001"
`dataWystawienia`	string (YYYY-MM-DD)	wymagane	Data wystawienia faktury
`dataSprzedazy`	string (YYYY-MM-DD)	wymagane	Data sprzedazy
`miejsceWystawienia`	string	opcjonalne	Miejsce wystawienia faktury
`terminPlatnosci`	string (YYYY-MM-DD)	opcjonalne	Termin platnosci
`metodaPlatnosci`	string	opcjonalne	Metoda platnosci: "przelew", "gotowka", "karta"
`sprzedawca`	object	wymagane	Dane sprzedawcy (patrz ponizej)
`nabywca`	object	wymagane	Dane nabywcy (patrz ponizej)
`pozycje`	array	wymagane	Lista pozycji na fakturze (min. 1)
`uwagi`	string	opcjonalne	Dodatkowe uwagi do faktury

Obiekt sprzedawca / nabywca

Pole	Typ	Wymagane	Opis
`nazwa`	string	wymagane	Pelna nazwa firmy
`nip`	string	wymagane	Numer NIP (10 cyfr)
`adres`	string	opcjonalne	Adres siedziby firmy
`kodPocztowy`	string	opcjonalne	Kod pocztowy (format XX-XXX)
`miasto`	string	opcjonalne	Miasto
`numerKonta`	string	opcjonalne	Numer konta bankowego (tylko sprzedawca)

Obiekt pozycji (element tablicy pozycje)

Pole	Typ	Wymagane	Opis
`nazwa`	string	wymagane	Nazwa uslugi lub towaru
`ilosc`	number	wymagane	Ilosc (wartosc > 0)
`jednostka`	string	opcjonalne	Jednostka miary: "szt.", "godz.", "usl.", "kg", "m"
`cenaNetto`	number	wymagane	Cena jednostkowa netto w zlotych
`stawkaVat`	number	wymagane	Stawka VAT: 23, 8, 5 lub 0

Format odpowiedzi

Endpoint /invoice/generate zwraca plik PDF (Content-Type: application/pdf).

Endpoint /invoice/preview zwraca odpowiedz JSON. Poprawne odpowiedzi zawieraja pole "status": "success". Odpowiedzi z bledem zawieraja pola "error" i "message".

Odpowiedz z bledem

          
          400 Bad Request
        
{
  "error": "Brak wymaganych pol",
  "message": "Pole \"numer\" jest wymagane"
}

Kody bledow

Status	Znaczenie
`400`	Nieprawidlowe zapytanie — brakujace lub bledne dane wejsciowe
`404`	Nie znaleziono — endpoint nie istnieje
`422`	Blad walidacji — dane nie spelniaja wymagan schematu
`429`	Za duzo zapytan — przekroczono limit zapytan
`500`	Blad serwera — wystapil nieoczekiwany problem

Limity zapytan

API stosuje ograniczenie czestotliwosci zapytan w celu ochrony jakosci uslugi:

Limit	Wartosc
Zapytania na minute	`30` na adres IP
Okno czasowe	`60 sekund` (okno przesuwne)

Po przekroczeniu limitu API zwraca status 429 z naglowkiem Retry-After.

Naglowki limitow sa dolaczane do kazdej odpowiedzi: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.

Przyklad cURL

          
          
          
          terminal
        
# Generowanie faktury PDF
curl -X POST "https://faktuj.pl/api/v1/invoice/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "numer": "FV/2026/02/001",
    "dataWystawienia": "2026-02-15",
    "dataSprzedazy": "2026-02-15",
    "sprzedawca": {
      "nazwa": "Kowalski Consulting Sp. z o.o.",
      "nip": "5213456789"
    },
    "nabywca": {
      "nazwa": "Nowak Software S.A.",
      "nip": "7891234560"
    },
    "pozycje": [{
      "nazwa": "Uslugi programistyczne",
      "ilosc": 160,
      "jednostka": "godz.",
      "cenaNetto": 150.00,
      "stawkaVat": 23
    }]
  }' --output faktura.pdf

# Podglad danych faktury (JSON)
curl -X POST "https://faktuj.pl/api/v1/invoice/preview" \
  -H "Content-Type: application/json" \
  -d '{"numer":"FV/2026/02/001","dataWystawienia":"2026-02-15","dataSprzedazy":"2026-02-15","sprzedawca":{"nazwa":"Kowalski Consulting Sp. z o.o.","nip":"5213456789"},"nabywca":{"nazwa":"Nowak Software S.A.","nip":"7891234560"},"pozycje":[{"nazwa":"Uslugi programistyczne","ilosc":160,"jednostka":"godz.","cenaNetto":150.00,"stawkaVat":23}]}'

Przyklad JavaScript

          
          
          
          app.js
        
const invoiceData = {
  numer: 'FV/2026/02/001',
  dataWystawienia: '2026-02-15',
  dataSprzedazy: '2026-02-15',
  sprzedawca: {
    nazwa: 'Kowalski Consulting Sp. z o.o.',
    nip: '5213456789'
  },
  nabywca: {
    nazwa: 'Nowak Software S.A.',
    nip: '7891234560'
  },
  pozycje: [{
    nazwa: 'Uslugi programistyczne',
    ilosc: 160,
    jednostka: 'godz.',
    cenaNetto: 150.00,
    stawkaVat: 23
  }]
};

// Generowanie PDF
const response = await fetch(
  'https://faktuj.pl/api/v1/invoice/generate',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(invoiceData)
  }
);
const blob = await response.blob();
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'faktura.pdf';
a.click();

// Podglad danych (JSON)
const preview = await fetch(
  'https://faktuj.pl/api/v1/invoice/preview',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(invoiceData)
  }
);
const data = await preview.json();
console.log(data);

Przyklad Python

          
          
          
          main.py
        
import requests

invoice_data = {
    "numer": "FV/2026/02/001",
    "dataWystawienia": "2026-02-15",
    "dataSprzedazy": "2026-02-15",
    "sprzedawca": {
        "nazwa": "Kowalski Consulting Sp. z o.o.",
        "nip": "5213456789"
    },
    "nabywca": {
        "nazwa": "Nowak Software S.A.",
        "nip": "7891234560"
    },
    "pozycje": [{
        "nazwa": "Uslugi programistyczne",
        "ilosc": 160,
        "jednostka": "godz.",
        "cenaNetto": 150.00,
        "stawkaVat": 23
    }]
}

# Generowanie PDF
response = requests.post(
    "https://faktuj.pl/api/v1/invoice/generate",
    json=invoice_data
)
with open("faktura.pdf", "wb") as f:
    f.write(response.content)

# Podglad danych (JSON)
preview = requests.post(
    "https://faktuj.pl/api/v1/invoice/preview",
    json=invoice_data
)
print(preview.json())