Oprogramowanie księgowe z interfejsem API

Każda funkcja systemu Nordlet jest dostępna poprzez jedno API JSON, z zestawami SDK, webhookami, powtórzeniami idempotentnymi oraz serwerem MCP dla asystentów AI.

Interfejs API (application programming interface) to sposób, w jaki jeden program komunikuje się z drugim. Finansowe API pozwala Twojemu oprogramowaniu wystawiać faktury, rejestrować płatności oraz generować raporty bez konieczności ręcznego klikania w interfejsie.

Nordlet to oprogramowanie księgowe, w którym interfejs API stanowi główną metodę dostępu. Wszystkie funkcje aplikacji webowej są dostępne za pośrednictwem tego samego API JSON. Ta strona jest przeznaczona dla deweloperów oraz osób decydujących o integracjach produktowych.

Co potrafi Nordlet

Jednolity format żądań. Każde wywołanie ma postać POST /v1/{module}/{resource}/{action} z treścią w formacie JSON, na przykład sales/invoices/create lub bank/transactions/match.
Klucze API z uprawnieniami (scopes). Każdy klucz należy do jednej spółki i posiada określone uprawnienia (scopes), takie jak sales:read lub bank:write. Klucz bez wymaganego uprawnienia otrzyma odpowiedź 403.
Pieniądze jako tekst. Kwoty są ciągami znaków o stałej precyzji do 4 miejsc po przecinku, a nie liczbami zmiennoprzecinkowymi, dzięki czemu nie dochodzi do strat groszowych w wyniku zaokrągleń.
Jednolity format błędów. Każdy błąd ma tę samą strukturę (envelope) zawierającą kod, komunikat oraz identyfikator żądania.
Wspólne zapytania dla list. Każde wywołanie list przyjmuje te same pola stronicowania, sortowania i filtrowania oraz może zwracać sumy.
Prawdziwe reguły księgowe. Zapisy księgowe (journal entries) muszą się bilansować, numery dokumentów nie mogą zawierać przerw, a zamknięty okres obrachunkowy (accounting period) odrzuca nowe księgowania z odpowiedzią 409. Każda zmiana jest zapisywana w dzienniku audytu (audit log).

Bezpieczne ponawianie dzięki idempotencji

Sieć może ulec awarii po przetworzeniu żądania, ale przed otrzymaniem odpowiedzi przez klienta. Ponowna próba mogłaby wtedy skutkować wystawieniem tej samej faktury dwukrotnie. Idempotencja (idempotency) oznacza, że powtórzone żądanie wywołuje taki sam skutek jak pierwsze.

Przekaż nagłówek Idempotency-Key przy każdym wywołaniu modyfikującym dane.
Ponowienie żądania z tym samym kluczem i tą samą treścią zwraca zapisaną wcześniej odpowiedź wraz z nagłówkiem x-idempotent-replay: true.
Użycie tego samego klucza z inną treścią jest odrzucane.
Klucze są przechowywane przez 24 godziny.

Webhooki

Webhook to komunikat wysyłany przez Nordlet do Twojego serwera w momencie wystąpienia określonego zdarzenia, takiego jak sale_invoice.paid.

Zdarzenia są zapisywane w tej samej transakcji bazy danych co zmiana, dzięki czemu wycofana zmiana nie generuje żadnego zdarzenia.
Każde doręczenie jest podpisane kluczem HMAC-SHA256 przy użyciu Twojego sekretu subskrypcji, co pozwala zweryfikować, że pochodzi ono z systemu Nordlet.
Nieudane doręczenie jest ponawiane przez około 24 godziny. Możesz je również wysłać ponownie ręcznie.
Subskrypcje można zarządzać w sekcji Konto → Webhooki lub za pośrednictwem API.

Narzędzia dla deweloperów

Dokumentacja API (API reference). Interaktywna dokumentacja API wygenerowana na podstawie opisu OpenAPI oraz kolekcja Postman.
Zestawy SDK. Typowane klienci dla języków TypeScript, Python, Go, Java, C#, Ruby, PHP, Swift i Rust, wygenerowani na podstawie tej samej specyfikacji. Zobacz przewodnik po SDK.
Serwer MCP. Asystented AI, tacy jak Claude, mogą przeszukiwać i wywoływać API przy użyciu Twojego klucza. Zobacz przewodnik po serwerze MCP.
Spółki testowe (sandbox). Spółka testowa działa jak prawdziwa, jest oznaczona jako dane testowe i wysyła deklaracje oraz e-faktury wyłącznie na testowe punkty końcowe administracji skarbowej.
Limit żądań (rate limit). 300 żądań na minutę dla jednego klucza API, z nagłówkami informującymi o pozostałym limicie.

FAQ

Co mogę zrobić za pomocą interfejsu API?

Wszystko, co oferuje produkt: fakturowanie, zakupy, księgę główną (general ledger), uzgadnianie płatności bankowych, magazyn, środki trwałe, płace, raporty oraz deklaracje podatkowe. Przewodnik dla początkujących przeprowadza przez pełny cykl od faktury do danych dla deklaracji VAT.

Czy mogę wbudować księgowość we własny produkt?

Tak. Każda spółka w systemie Nordlet posiada własne księgi, a Twoje oprogramowanie zarządza nimi poprzez przypisany klucz API. API nie zawiera metod umożliwiających edycję lub usuwanie zatwierdzonego zapisu księgowego. Korekta wymaga utworzenia nowego zapisu, co gwarantuje zachowanie niezmienialności ksiąg (immutable ledger).