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/proforma

POST /api/v1/invoice/proforma

Generuje fakture proforma w formacie PDF. Faktura proforma to dokument informacyjny / oferta — nie stanowi podstawy do odliczenia VAT. Schemat zapytania jest identyczny jak w /invoice/generate (pole typDokumentu jest ustawiane automatycznie na "proforma").

Przykladowe zapytanie

          
          
          
          cURL
        
curl -X POST "https://faktuj.pl/api/v1/invoice/proforma" \
  -H "Content-Type: application/json" \
  -d '{
    "numer": "PRO/2026/03/001",
    "dataWystawienia": "2026-03-06",
    "dataSprzedazy": "2026-03-06",
    "terminPlatnosci": "2026-03-20",
    "metodaPlatnosci": "przelew",
    "miejsceWystawienia": "Warszawa",
    "sprzedawca": {
      "nazwa": "Kowalski Consulting Sp. z o.o.",
      "nip": "5213456789",
      "adres": "ul. Marszalkowska 1",
      "kodPocztowy": "00-001",
      "miasto": "Warszawa"
    },
    "nabywca": {
      "nazwa": "Nowak Software S.A.",
      "nip": "7891234560",
      "adres": "ul. Krakowska 50",
      "kodPocztowy": "31-066",
      "miasto": "Krakow"
    },
    "pozycje": [{
      "nazwa": "Uslugi programistyczne",
      "ilosc": 160,
      "jednostka": "godz.",
      "cenaNetto": 150.00,
      "stawkaVat": 23
    }]
  }' \
  --output proforma.pdf

Odpowiedz

Identyczna jak /invoice/generate — plik PDF z naglowkiem Content-Disposition: attachment; filename="proforma-PRO-2026-03-001.pdf". Tytul dokumentu to FAKTURA PROFORMA zamiast FAKTURA VAT, a stopka zawiera informacje, ze dokument nie stanowi podstawy do odliczenia VAT.

POST /invoice/duplicate

POST /api/v1/invoice/duplicate

Generuje duplikat faktury VAT (Duplikat Faktury) w formacie PDF. Duplikat jest ponownym wystawieniem oryginalnej faktury z naglowkiem FAKTURA VAT — DUPLIKAT, znakiem wodnym "DUPLIKAT" oraz data wystawienia duplikatu. Wymagane prawnie gdy oryginal zostal zagubiony lub zniszczony (art. 106l ustawy o VAT).

Dodatkowe pole

Pole	Typ	Wymagane	Opis
`dataDuplikatu`	string	opcjonalne	Data wystawienia duplikatu w formacie RRRR-MM-DD. Jesli pominiete, ustawiana jest data dzisiejsza.

Pozostale pola sa identyczne jak w /invoice/generate (pole typDokumentu jest ustawiane automatycznie na "duplikat").

Przykladowe zapytanie

          
          
          
          cURL
        
curl -X POST "https://faktuj.pl/api/v1/invoice/duplicate" \
  -H "Content-Type: application/json" \
  -d '{
    "numer": "FV/2026/02/001",
    "dataDuplikatu": "2026-03-06",
    "dataWystawienia": "2026-02-15",
    "dataSprzedazy": "2026-02-15",
    "terminPlatnosci": "2026-03-01",
    "metodaPlatnosci": "przelew",
    "miejsceWystawienia": "Warszawa",
    "sprzedawca": {
      "nazwa": "Kowalski Consulting Sp. z o.o.",
      "nip": "5213456789",
      "adres": "ul. Marszalkowska 1",
      "kodPocztowy": "00-001",
      "miasto": "Warszawa"
    },
    "nabywca": {
      "nazwa": "Nowak Software S.A.",
      "nip": "7891234560",
      "adres": "ul. Krakowska 50",
      "kodPocztowy": "31-066",
      "miasto": "Krakow"
    },
    "pozycje": [{
      "nazwa": "Usluga programistyczna",
      "ilosc": 160,
      "jednostka": "godz.",
      "cenaNetto": 150.00,
      "stawkaVat": 23
    }]
  }' \
  --output duplikat.pdf

Odpowiedz

Identyczna jak /invoice/generate — plik PDF z naglowkiem Content-Disposition: attachment; filename="duplikat-FV-2026-02-001.pdf". Tytul dokumentu to FAKTURA VAT — DUPLIKAT, dokument zawiera znak wodny "DUPLIKAT" oraz date wystawienia duplikatu.

POST /invoice/correction

POST /api/v1/invoice/correction

Generuje fakture korygujaca (Faktura Korygujaca) w formacie PDF. Wymaga dodatkowych pol: numeru faktury oryginalnej, daty faktury oryginalnej i przyczyny korekty. Tytul dokumentu to FAKTURA KORYGUJACA.

Dodatkowe pola (wymagane)

Pole	Typ	Opis
`numerOryginalny`	string	Numer faktury oryginalnej, do ktorej wystawiana jest korekta
`dataOryginalnej`	string (YYYY-MM-DD)	Data wystawienia faktury oryginalnej
`przyczynaKorekty`	string	Przyczyna wystawienia korekty (np. "Blad w cenie netto")

Przyklad

terminal
curl -X POST "https://faktuj.pl/api/v1/invoice/correction" \
  -H "Content-Type: application/json" \
  -d '{
    "numer": "FK/2026/03/001",
    "dataWystawienia": "2026-03-06",
    "dataSprzedazy": "2026-01-15",
    "terminPlatnosci": "2026-03-20",
    "metodaPlatnosci": "przelew",
    "miejsceWystawienia": "Warszawa",
    "numerOryginalny": "FV/2026/01/001",
    "dataOryginalnej": "2026-01-15",
    "przyczynaKorekty": "Blad w cenie netto pozycji nr 1",
    "sprzedawca": {
      "nazwa": "Kowalski Consulting Sp. z o.o.",
      "nip": "5213456789",
      "adres": "ul. Marszalkowska 1",
      "kodPocztowy": "00-001",
      "miasto": "Warszawa"
    },
    "nabywca": {
      "nazwa": "Nowak Software S.A.",
      "nip": "7891234560",
      "adres": "ul. Krakowska 50",
      "kodPocztowy": "31-066",
      "miasto": "Krakow"
    },
    "pozycje": [{
      "nazwa": "Usluga programistyczna (po korekcie)",
      "ilosc": 160,
      "jednostka": "godz.",
      "cenaNetto": 160.00,
      "stawkaVat": 23
    }]
  }' \
  --output korekta.pdf

Odpowiedz

Plik PDF z naglowkiem Content-Disposition: attachment; filename="korekta-FK-2026-03-001.pdf". Tytul dokumentu to FAKTURA KORYGUJACA, zawiera odniesienie do faktury oryginalnej i przyczyne korekty.

POST /invoice/advance

POST /api/v1/invoice/advance

Generuje fakture zaliczkowa (Faktura Zaliczkowa) w formacie PDF. Dokumentuje otrzymana zaliczke przed wykonaniem uslugi lub dostarczeniem towaru. Wymaga dodatkowego pola kwotaZaliczki. Opcjonalnie mozna podac numerZamowienia.

Dodatkowe pola

Pole	Typ	Wymagane	Opis
`kwotaZaliczki`	number	tak	Kwota otrzymanej zaliczki (brutto, w PLN)
`numerZamowienia`	string	nie	Numer zamowienia, do ktorego odnosi sie zaliczka

Przyklad

terminal
curl -X POST "https://faktuj.pl/api/v1/invoice/advance" \
  -H "Content-Type: application/json" \
  -d '{
    "numer": "FZ/2026/03/001",
    "dataWystawienia": "2026-03-07",
    "dataSprzedazy": "2026-03-07",
    "terminPlatnosci": "2026-03-14",
    "metodaPlatnosci": "przelew",
    "miejsceWystawienia": "Warszawa",
    "kwotaZaliczki": 5000.00,
    "numerZamowienia": "ZAM/2026/001",
    "sprzedawca": {
      "nazwa": "Kowalski Consulting Sp. z o.o.",
      "nip": "5213456789",
      "adres": "ul. Marszalkowska 1",
      "kodPocztowy": "00-001",
      "miasto": "Warszawa"
    },
    "nabywca": {
      "nazwa": "Nowak Software S.A.",
      "nip": "7891234560",
      "adres": "ul. Krakowska 50",
      "kodPocztowy": "31-066",
      "miasto": "Krakow"
    },
    "pozycje": [{
      "nazwa": "Usluga programistyczna",
      "ilosc": 160,
      "jednostka": "godz.",
      "cenaNetto": 150.00,
      "stawkaVat": 23
    }]
  }' \
  --output zaliczkowa.pdf

Odpowiedz

Plik PDF z naglowkiem Content-Disposition: attachment; filename="zaliczkowa-FZ-2026-03-001.pdf". Tytul dokumentu to FAKTURA ZALICZKOWA, zawiera rozliczenie zaliczki z kwota do zaplaty.

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 }
      }
    }
  }
}

POST /invoice/batch

POST /api/v1/invoice/batch

Generuje do 20 faktur w jednym zapytaniu. Kazda faktura jest walidowana i generowana niezaleznie — blad w jednej fakturze nie blokuje pozostalych. Odpowiedz zawiera tablice wynikow z plikami PDF zakodowanymi w base64.

Schemat zapytania

Pole	Typ	Wymagane	Opis
`faktury`	array	Tak	Tablica obiektow faktur (max 20). Kazdy obiekt ma ten sam schemat co `POST /invoice/generate`

Odpowiedz

Pole	Typ	Opis
`status`	string	`"success"` jesli co najmniej jedna faktura wygenerowana, `"error"` jesli wszystkie zawiodly
`count`	number	Liczba faktur w zapytaniu
`generated`	number	Liczba pomyslnie wygenerowanych faktur
`errors`	number	Liczba faktur z bledami
`results`	array	Tablica wynikow — po jednym na kazda fakture
`results[].index`	number	Indeks faktury w oryginalnej tablicy (od 0)
`results[].numer`	string	Numer faktury
`results[].status`	string	`"success"` lub `"error"`
`results[].pdf`	string	Plik PDF zakodowany w base64 (tylko przy `status: "success"`)
`results[].filename`	string	Sugerowana nazwa pliku PDF
`results[].size`	number	Rozmiar PDF w bajtach
`results[].errors`	array	Bledy walidacji (tylko przy `status: "error"`)

Przyklad

cURL
curl -X POST "https://faktuj.pl/api/v1/invoice/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "faktury": [
      {
        "numer": "FV/2026/03/001",
        "dataWystawienia": "2026-03-10",
        "dataSprzedazy": "2026-03-10",
        "terminPlatnosci": "2026-03-24",
        "metodaPlatnosci": "przelew",
        "miejsceWystawienia": "Warszawa",
        "sprzedawca": { "nazwa": "Firma Sp. z o.o.", "nip": "5213456789", "adres": "ul. Testowa 1", "kodPocztowy": "00-001", "miasto": "Warszawa" },
        "nabywca": { "nazwa": "Klient S.A.", "nip": "7891234560", "adres": "ul. Odbiorcza 5", "kodPocztowy": "31-066", "miasto": "Krakow" },
        "pozycje": [{ "nazwa": "Usluga", "ilosc": 1, "jednostka": "szt.", "cenaNetto": 1000, "stawkaVat": 23 }]
      },
      {
        "numer": "FV/2026/03/002",
        "dataWystawienia": "2026-03-10",
        "dataSprzedazy": "2026-03-10",
        "terminPlatnosci": "2026-03-24",
        "metodaPlatnosci": "przelew",
        "miejsceWystawienia": "Warszawa",
        "sprzedawca": { "nazwa": "Firma Sp. z o.o.", "nip": "5213456789", "adres": "ul. Testowa 1", "kodPocztowy": "00-001", "miasto": "Warszawa" },
        "nabywca": { "nazwa": "Inny Klient Sp. z o.o.", "nip": "1234567890", "adres": "ul. Inna 10", "kodPocztowy": "02-100", "miasto": "Warszawa" },
        "pozycje": [{ "nazwa": "Konsultacja", "ilosc": 8, "jednostka": "godz.", "cenaNetto": 200, "stawkaVat": 23 }]
      }
    ]
  }'

GET /nip/:nip

GET /api/v1/nip/:nip

Wyszukuje dane firmy po numerze NIP w rejestrze Ministerstwa Finansow (Biala Lista VAT). Zwraca nazwe firmy, adres, kod pocztowy, miasto oraz numer konta bankowego (jezeli dostepny). Przydatne do automatycznego uzupelniania danych sprzedawcy lub nabywcy w formularzu faktury.

Parametry URL

Parametr	Typ	Opis
`nip`	string (10 cyfr)	Numer Identyfikacji Podatkowej firmy

Przykladowe zapytanie

          
          cURL
        
curl "https://faktuj.pl/api/v1/nip/5213456789"

Przykladowa odpowiedz

          
          
          
          200 OK
        
{
  "status": "success",
  "nazwa": "KOWALSKI CONSULTING SP. Z O.O.",
  "adres": "ul. Marszalkowska 10",
  "kodPocztowy": "00-624",
  "miasto": "WARSZAWA",
  "numerKonta": "PL61109010140000071219812874"
}

Jezeli podmiot nie zostanie znaleziony, API zwraca status 404. Jezeli NIP ma niepoprawny format, zwraca 400.

GET /nbp/:currency/:date

GET /api/v1/nbp/:currency/:date

Pobiera kurs sredni NBP (Narodowy Bank Polski) dla podanej waluty i daty. Przydatne do automatycznego uzupelniania kursu na fakturach walutowych. Korzysta z tabeli A kursow srednich NBP.

Parametry URL

Parametr	Typ	Opis
`currency`	string (3 litery)	Kod waluty ISO 4217 (np. EUR, USD, GBP, CHF)
`date`	string (YYYY-MM-DD)	Data, dla ktorej szukamy kursu

Przykladowe zapytanie

          
          cURL
        
curl "https://faktuj.pl/api/v1/nbp/EUR/2026-03-07"

Przykladowa odpowiedz

          
          
          
          200 OK
        
{
  "status": "success",
  "waluta": "EUR",
  "nazwaWaluty": "euro",
  "kurs": 4.3125,
  "dataKursu": "2026-03-07",
  "tabelaNBP": "045/A/NBP/2026"
}

Jezeli kurs nie jest dostepny dla podanej daty (weekend, dzien swiateczny), API zwraca status 404. Uzyj ostatniego dnia roboczego przed data sprzedazy, zgodnie z art. 31a ustawy o VAT.

GET /iban/:iban

Walidacja numeru IBAN. Sprawdza format, sume kontrolna (MOD 97-10), a dla polskich IBAN-ow identyfikuje bank na podstawie kodu rozliczeniowego.

Zapytanie
curl https://faktuj.pl/api/v1/iban/PL61109010140000071219812874

Odpowiedz
{
  "status": "success",
  "valid": true,
  "iban": "PL61109010140000071219812874",
  "kodKraju": "PL",
  "kodBanku": "1090",
  "nazwabanku": "Santander Bank Polska"
}

IBAN moze zawierac spacje i myslniki — zostana automatycznie usuniete. Obslugiwane sa IBAN-y z dowolnego kraju (walidacja sumy kontrolnej), ale identyfikacja nazwy banku dostepna jest tylko dla polskich IBAN-ow (prefix PL).

Faktury walutowe (Multi-Currency)

Wszystkie endpointy generowania faktur obsluguja waluty obce. Dodaj pola walutowe do zapytania, aby wygenerowac fakture w obcej walucie z przeliczeniem na PLN:

Dodatkowe pola walutowe

Pole	Typ	Wymagane	Opis
`waluta`	string	opcjonalne	Kod waluty ISO 4217 (np. EUR, USD, GBP). Domyslnie: PLN
`kursNBP`	number	opcjonalne	Kurs sredni NBP. Pobierany automatycznie z API NBP gdy pominiete (kurs z ostatniego dnia roboczego przed data sprzedazy)
`tabelaNBP`	string	opcjonalne	Nr tabeli NBP (np. "045/A/NBP/2026")
`dataKursu`	string (YYYY-MM-DD)	opcjonalne	Data kursu NBP

Przyklad faktury w EUR

          
          
          
          cURL
        
curl -X POST "https://faktuj.pl/api/v1/invoice/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "numer": "FV/2026/03/001",
    "dataWystawienia": "2026-03-08",
    "dataSprzedazy": "2026-03-08",
    "terminPlatnosci": "2026-03-22",
    "metodaPlatnosci": "przelew",
    "miejsceWystawienia": "Warszawa",
    "waluta": "EUR",
    "kursNBP": 4.3125,
    "tabelaNBP": "045/A/NBP/2026",
    "dataKursu": "2026-03-07",
    "sprzedawca": {
      "nazwa": "Kowalski Consulting Sp. z o.o.",
      "nip": "5213456789",
      "adres": "ul. Marszalkowska 1",
      "kodPocztowy": "00-001",
      "miasto": "Warszawa"
    },
    "nabywca": {
      "nazwa": "Acme GmbH",
      "nip": "7891234560",
      "adres": "Berliner Str. 10",
      "kodPocztowy": "31-066",
      "miasto": "Berlin"
    },
    "pozycje": [{
      "nazwa": "Consulting services",
      "ilosc": 10,
      "jednostka": "godz.",
      "cenaNetto": 100.00,
      "stawkaVat": 23
    }]
  }' --output faktura-eur.pdf

Wygenerowany PDF zawiera kwoty w walucie obcej oraz sekcje "Przeliczenie na PLN" z kursem NBP, numerem tabeli i rownowartoscia w zlotych.

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
`mechanizmPodzielonejPlatnosci`	boolean	opcjonalne	Oznaczenie "Mechanizm podzielonej platnosci" (split payment) — wymagane dla niektorych transakcji powyzej 15 000 PLN
`typDokumentu`	string	opcjonalne	Typ dokumentu: `"vat"` (domyslny), `"proforma"`, `"duplikat"`, `"korygujaca"`, lub `"zaliczkowa"`. Ustawiane automatycznie przy uzyciu dedykowanych endpointow
`dataDuplikatu`	string (YYYY-MM-DD)	opcjonalne	Data wystawienia duplikatu — wymagane gdy `typDokumentu` = `"duplikat"`. Jesli pominiete w endpoincie `/invoice/duplicate`, ustawiana jest data dzisiejsza
`numerOryginalny`	string	opcjonalne	Numer faktury oryginalnej — wymagane gdy `typDokumentu` = `"korygujaca"`
`dataOryginalnej`	string (YYYY-MM-DD)	opcjonalne	Data wystawienia faktury oryginalnej — wymagane gdy `typDokumentu` = `"korygujaca"`
`przyczynaKorekty`	string	opcjonalne	Przyczyna wystawienia korekty — wymagane gdy `typDokumentu` = `"korygujaca"`
`kwotaZaliczki`	number	opcjonalne	Kwota otrzymanej zaliczki (brutto, PLN) — wymagane gdy `typDokumentu` = `"zaliczkowa"`
`numerZamowienia`	string	opcjonalne	Numer zamowienia — opcjonalne, wyswietlane na fakturze zaliczkowej
`waluta`	string	opcjonalne	Kod waluty ISO 4217 (np. EUR, USD, GBP). Domyslnie: PLN. Patrz Faktury walutowe
`kursNBP`	number	opcjonalne	Kurs sredni NBP — pobierany automatycznie z API NBP gdy pominiete
`tabelaNBP`	string	opcjonalne	Nr tabeli kursow NBP (np. "045/A/NBP/2026") — uzupelniany automatycznie z NBP
`dataKursu`	string (YYYY-MM-DD)	opcjonalne	Data kursu NBP — uzupelniana automatycznie z NBP
`logo`	string	opcjonalne	Logo firmy jako data URI base64 (PNG lub JPEG, maks. ~500KB). Format: `data:image/png;base64,...`. Logo pojawi sie w lewym gornym rogu dokumentu PDF
`okresSprzedazy`	object	opcjonalne	Okres sprzedazy dla faktur uslugowych/abonamentowych. Obiekt z polami `od` i `do` (format YYYY-MM-DD). Na PDF zamiast "Data sprzedazy" wyswietla sie "Okres sprzedazy: RRRR-MM-DD — RRRR-MM-DD"
`metadata`	boolean	opcjonalne	Gdy `true`, odpowiedz to JSON z PDF (base64) + obliczonymi danymi faktury (pozycje, podsumowanie VAT, kwoty netto/brutto, kwota slownie). Domyslnie: `false` (zwraca surowy PDF). Dostepne we wszystkich endpointach generowania faktur oraz w batch

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 metadanymi (metadata: true)

Wszystkie endpointy generowania faktur (generate, proforma, duplicate, correction, advance, batch) obsluguja opcjonalne pole "metadata": true. Gdy ustawione, odpowiedz to JSON z PDF (base64) oraz obliczonymi danymi faktury:

          
          
          
          200 OK (metadata: true)
        
{
  "status": "success",
  "numer": "FV/2026/02/001",
  "typDokumentu": "vat",
  "pdf": "JVBERi0xLjQ...",
  "filename": "faktura-FV-2026-02-001.pdf",
  "size": 42156,
  "pozycje": [
    {
      "lp": 1,
      "nazwa": "Usluga programistyczna",
      "ilosc": 160,
      "jednostka": "godz.",
      "cenaNetto": 150,
      "stawkaVat": 23,
      "wartoscNetto": 24000,
      "kwotaVat": 5520,
      "wartoscBrutto": 29520
    }
  ],
  "vatBreakdown": [
    { "stawkaVat": 23, "netto": 24200, "vat": 5566, "brutto": 29766 }
  ],
  "razemNetto": 24200,
  "razemVat": 5566,
  "razemBrutto": 29766,
  "kwotaSlownie": "dwadziescia dziewiec tysiecy siedemset szescdziesiat szesc zlotych 00/100",
  "waluta": "PLN"
}

Uzyj tego trybu, aby zapisac dane faktury w bazie danych bez parsowania PDF, lub jako podstawe do generowania formatow ustrukturyzowanych (np. KSeF XML).

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())

Integracja MCP (Model Context Protocol)

Faktuj wspiera Model Context Protocol (MCP), umozliwiajac asystentom AI takim jak Claude, VS Code Copilot, Cursor i innym klientom kompatybilnym z MCP bezposrednie generowanie polskich faktur VAT (Faktura VAT).

Instalacja

Dodaj ponizszy wpis do pliku claude_desktop_config.json (lub odpowiedniej konfiguracji klienta MCP):

          
          
          
          claude_desktop_config.json
        
{
  "mcpServers": {
    "faktuj": {
      "command": "npx",
      "args": ["-y", "faktuj-mcp"]
    }
  }
}

Dostepne narzedzia

Narzedzie	Opis	Parametry
`generate_invoice`	Generuje fakture VAT i zwraca plik PDF	Pelne dane faktury (sprzedawca, nabywca, pozycje — patrz schemat zapytania)
`preview_invoice`	Zwraca podglad danych faktury w formacie JSON z obliczonymi kwotami	Pelne dane faktury (identyczne jak `generate_invoice`)

Zmienne srodowiskowe

Zmienna	Domyslna wartosc	Opis
`FAKTUJ_BASE_URL`	`https://faktuj.pl`	Nadpisuje bazowy URL dla zapytan API (przydatne dla instancji self-hosted)