Nordlet

← All features

Nordlet dla twórców aplikacji

Dodaj fakturowanie, księgowość i unijne deklaracje podatkowe do swojego oprogramowania za pomocą jednego interfejsu JSON API, silnie typowanych pakietów SDK, webhooków, serwera MCP i firm testowych (sandbox).

Wiele aplikacji generuje zdarzenia finansowe: opłacone zamówienie, odnowioną subskrypcję czy zwrócone środki. Każde takie zdarzenie musi trafić do ksiąg rachunkowych firmy.

Nordlet to oprogramowanie księgowo-finansowe stworzone w architekturze API-first. Wszystko, co oferuje aplikacja internetowa, jest również dostępne za pośrednictwem jednego interfejsu JSON API. Twoja aplikacja przesyła zdarzenia, a Nordlet prowadzi księgi oraz przygotowuje deklaracje podatkowe.

Co robi Nordlet

  • Udostępnia każdą akcję w formacie POST /v1/{module}/{resource}/{action} z ciałem w formacie JSON, na przykład /v1/sales/invoices/create.
  • Uwierzytelnia każde żądanie za pomocą klucza API przypisanego do jednej firmy. Każdy klucz posiada określone uprawnienia (scopes), takie jak sales:read lub sales:write, które ograniczają jego możliwości.
  • Przyjmuje kwoty jako ciągi znaków o stałej precyzji (decimal strings), a nigdy jako liczby zmiennoprzecinkowe, dzięki czemu żadne centy nie giną w wyniku zaokrągleń.
  • Obsługuje nagłówek Idempotency-Key przy każdej modyfikacji danych. Ponowne wysłanie żądania z tym samym kluczem zwraca pierwszą odpowiedź zamiast wykonywać operację po raz drugi. Idempotencja oznacza, że powtórzone żądanie wywołuje taki sam skutek jak jedno żądanie.
  • Zwraca każdy błąd w jednym, wspólnym formacie.
  • Pozwala na 300 żądań na minutę dla jednego klucza API.
  • Rejestruje każdą zmianę w dzienniku audytu (audit log).

Przewodnik po konwencjach API omawia każdą z tych zasad szczegółowo.

Księgi, które pozostają poprawne

  • Wystawienie faktury nadaje numer z zachowaniem ciągłości (gapless number), sprawdza, czy okres sprawozdawczy jest otwarty, oraz księguje wpis do dziennika w ramach tej samej transakcji bazy danych.
  • Każdy zapis księgowy musi się bilansować. Baza danych weryfikuje to automatycznie podczas zapisywania transakcji.
  • Wystawionych i zarejestrowanych dokumentów nie można usuwać. Błędne przypisanie płatności bankowej koryguje się zapisem przeciwstawnym, a nie poprzez edycję pierwotnego dokumentu. Na tym polega działanie niezmienniczej księgi rachunkowej (immutable ledger).

Pakiety SDK, MCP i webhooki

  • Silnie typowane pakiety SDK są generowane z tej samej specyfikacji OpenAPI dla języków TypeScript, Python, Go, Java, C#, Ruby, PHP, Swift oraz Rust. Do momentu opublikowania oficjalnej paczki można zainstalować ją bezpośrednio z repozytorium źródłowego. Zobacz przewodnik po pakietach SDK.
  • Dostępna jest kolekcja Postman zawierająca wszystkie punkty końcowe (endpoints).
  • Serwer MCP pozwala asystentowi AI, takiemu jak Claude Code, przeszukiwać API i wywoływać je za pomocą Twojego klucza API. Każde wywołanie jest zwykłym żądaniem API z zachowaniem tych samych uprawnień i limitów.
  • Webhooki informują Twoją aplikację o wystąpieniu zdarzenia, na przykład sale_invoice.issued lub sale_invoice.paid. Każda dostarczenie jest zabezpieczone podpisem HMAC, co pozwala zweryfikować, że pochodzi ono od Nordlet. Nieudane próby dostarczenia są ponawiane przez około 24 godziny.

Testowanie z firmami testowymi (sandbox)

  • Utwórz firmę z flagą isSandbox: true lub zaznacz pole sandbox podczas konfiguracji firmy w aplikacji.
  • Firma testowa działa tak samo jak rzeczywista: te same moduły, ten sam interfejs API.
  • Jest ona wyraźnie oznaczona jako dane testowe, a firmy rzeczywistej nie można przekształcić w testową i odwrotnie.
  • Deklaracje oraz e-faktury firmy testowej trafiają do środowisk testowych administracji skarbowych.
  • Korzystanie z firmy testowej podlega pomiarowi zużycia i rozliczeniom na takich samych zasadach jak firma rzeczywista.

Przewodnik dla początkujących przeprowadzi Cię krok po kroku przez uzyskanie pierwszego klucza API, wystawienie pierwszej faktury oraz cały cykl rozliczeniowy.

FAQ

Czy jedna aplikacja może obsługiwać kilka firm?

Tak. Każdy klucz API jest przypisany do jednej firmy, dlatego tworzysz osobny klucz dla każdego podmiotu. Każde powiadomienie webhook zawiera identyfikator companyId powiązany z odpowiednią firmą, dzięki czemu jeden odbiornik (receiver) może obsługiwać wiele firm.

Czy muszę samodzielnie tworzyć deklaracje podatkowe?

Nie. Nordlet generuje deklaracje bezpośrednio na podstawie ksiąg rachunkowych. W zależności od kraju system wysyła deklarację automatycznie, przygotowuje plik do ręcznego przesłania lub wyświetla dane do wpisania w portalach urzędowych. Tabela wsparcia deklaracji zawiera szczegółowe informacje dla każdego kraju.

Powiązane