Przejdź do treści

Programiści

API faktur

Bezpłatnie odczytuj z własnego kodu faktury, kontrahentów, firmy, płatności, harmonogramy cykliczne, przesłane pliki dostawców, raporty VAT i wiekowania należności oraz priorytetową listę kolejnych działań. Lifetime Pro za jednorazowe 49 € z podatkiem dodaje operacje zapisu i wychodzące webhooki, bez opłat miesięcznych i corocznego odnowienia.

Podstawowy adres URL

https://freebillgen.com/api/v1

Uwierzytelnianie

Każde żądanie korzysta z tokena Bearer. Należy utworzyć go w Ustawienia → Klucze API, nadać mu wymagane zakresy odczytu i zapisu dla poszczególnych zasobów, opcjonalnie ustawić termin wygaśnięcia i wysyłać go przy każdym żądaniu:

Authorization: Bearer <własny-klucz-api>

Żądania są uwierzytelniane na koncie, które utworzyło klucz, i sprawdzane względem przypisanych zakresów. Token należy przechowywać w tajemnicy i unieważnić po ujawnieniu albo gdy nie jest już potrzebny.

Co można robić

  • Odczytywać faktury, kontrahentów, firmy, płatności i harmonogramy cykliczne
  • Tworzyć je i aktualizować (API do zapisu - Pro)
  • Pobierać raporty VAT i wiekowania należności jako JSON
  • Odczytywać tę samą ograniczoną kolejkę kolejnych działań, z której korzysta panel
  • Odczytywać pliki e-faktur dostawców przesłane ręcznie do skrzynki odbiorczej (nie jest to punkt odbioru Peppol ani poczty e-mail)
  • Pobierać ogólne mapowania OASIS UBL i UN/CEFACT CII do przeglądu (bez walidacji profilu)
  • Rejestrować punkty końcowe webhooków dla zdarzeń faktur i płatności (Pro)
  • Stosować Idempotency-Key przy obsługiwanych zapisach: zmiana danych żądania pod tym samym kluczem zwraca 409
  • Korzystać z paginacji kursorowej przez links.next, regulowanej parametrem per_page (maks. 100)
  • Udostępniać faktury agentom AI przez schema.org/Invoice JSON-LD oraz nagłówek Accept: application/json lub text/markdown dla każdego podpisanego odsyłacza
  • Korzystać z nieuwierzytelnianego serwera MCP tylko do odczytu pod adresem https://freebillgen.com/api/mcp (get_invoice, verify_invoice)

Konwencje

Idempotencja
Przy obsługiwanych wywołaniach tworzenia i akcji należy wysłać unikalny nagłówek Idempotency-Key. Ponowienie żądania z identycznymi danymi odtwarza pierwotny sukces, a zmienione dane zwracają kod 409.
Paginacja
Listy zapisanych zasobów korzystają z paginacji kursorowej. Należy przechodzić przez links.next lub przekazać ?cursor=... oraz ustawić ?per_page=, maksymalnie 100. Ograniczona lista działań zwraca swój limit i informację o obcięciu.
Kwoty
Kwoty pieniężne są dokładnymi ciągami JSON sformatowanymi zgodnie ze skalą ISO 4217 danej waluty, np. "121.00" dla EUR lub "500" dla JPY. Ceny jednostkowe mogą zachowywać większą precyzję wejściową.
Identyfikatory
Każdy zasób jest adresowany nieinterpretowalnym identyfikatorem, nigdy kolejnym numerem.

Przykład: wylistuj swoje faktury

curl https://freebillgen.com/api/v1/invoices \
  -H "Authorization: Bearer $FREEBILLGEN_API_KEY"

Otwórz pełną interaktywną dokumentację API →

Pytania o API faktur

Czy API faktur jest darmowe?

Tak. API do odczytu jest bezpłatnie dostępne w planie darmowym. API do zapisu i wychodzące webhooki obejmuje Lifetime Pro za jednorazowe 49 € z podatkiem, bez opłat miesięcznych i corocznego odnowienia.

Jak działa uwierzytelnianie?

Token Bearer należy utworzyć w Ustawienia → Klucze API, przypisać mu zakresy odczytu lub zapisu dla poszczególnych zasobów i wysyłać go jako nagłówek Authorization: Bearer przy każdym żądaniu. Klucze są ograniczone do danego konta i można je unieważnić lub ustawić im termin wygaśnięcia.

Czy mogę tworzyć faktury programowo?

Tak, przez API do zapisu dostępne w dodatku Pro. Tworzy ono takie same profesjonalne faktury jak aplikacja internetowa, z numeracją sekwencyjną i konfigurowalną obsługą VAT po stronie serwera. API nie poświadcza zgodności z lokalnymi przepisami.

Jak uniknąć tworzenia zduplikowanych faktur przy ponowieniu?

Przy wywołaniu tworzenia należy wysłać unikalny nagłówek Idempotency-Key. Ponowienie identycznych danych z tym kluczem zwraca pierwotny wynik. Ponowne użycie klucza ze zmienionymi danymi zwraca kod 409 zamiast bez ostrzeżenia odtworzyć inną fakturę.

Czy mogę odczytywać faktury, które otrzymałem?

Tak, bez opłat. GET /api/v1/inbox zwraca obsługiwane pliki dostawców UBL/CII przesłane ręcznie i przetworzone przez FreeBillGen, z zachowaniem oryginału do audytu. GET /api/v1/inbox/{id} zwraca pojedynczy plik. Rozpoznanie składni nie jest walidacją profilu, a te punkty końcowe nie czynią z FreeBillGen punktu odbioru Peppol, sieci administracji ani faktur przesyłanych e-mailem.

Czy agent AI może odczytać fakturę bez konta?

Tak. Każda faktura udostępniona przez podpisany publiczny odsyłacz jest dostępna dla agenta pod tym samym adresem URL. Strona osadza schema.org/Invoice JSON-LD, nagłówek Accept: application/json zwraca ustrukturyzowaną fakturę obejmującą strony, pozycje, sumy, saldo i opcje płatności, a Accept: text/markdown zwraca czytelną reprezentację o małej liczbie tokenów. Pod adresem https://freebillgen.com/api/mcp działa też nieuwierzytelniany serwer Model Context Protocol (MCP) tylko do odczytu z narzędziami get_invoice i verify_invoice. Podpis odsyłacza jest tokenem dostępu. Pełny adres URL trzeba traktować jak tajny, ponieważ każda osoba, która go otrzyma, może otworzyć fakturę.

Bezpłatny klucz API

Należy utworzyć konto, otworzyć Ustawienia → Klucze API i bezpłatnie zacząć od API do odczytu. Karta nie jest wymagana. Gdy później potrzebne będą operacje zapisu lub wychodzące webhooki, Lifetime Pro kosztuje jednorazowo 49 € z podatkiem i nie podlega odnowieniu.

Utwórz konto