API księgowe proszę oceniać według ośmiu rzeczy, które da się zweryfikować z dokumentacji w jedno popołudnie: jak wywołujący się uwierzytelnia i wobec którego najemcy, czy uprawnienia są ograniczone zakresami, czy zapisy są idempotentne, czy API informuje o zmianach (webhooki), jaki jest limit zapytań i jak zawodzi, czy istnieje sandbox, jak wygląda błąd oraz czy asystent AI może z niego korzystać, nie mogąc wyrządzić szkody. Dostawca, który na wszystkie osiem odpowiada konkretami, przemyślał integracje; dostawca, który odpowiada „tak”, nie. Ta strona podaje pytania, a następnie odpowiedzi KRONENWERK z prawdziwymi liczbami i prawdziwymi ograniczeniami.
Dlaczego API decyduje o więcej niż lista funkcji
System księgowy, do którego pisze Państwa produkt, staje się częścią Państwa produktu. Jego API kształtuje to, jak modelują Państwo klientów i faktury, jak odzyskują się Państwo po nieudanym żądaniu o 3 w nocy i co widzi audytor, gdy pyta, który system utworzył zapis. Wybór na podstawie listy funkcji i odkrycie API później to droga, którą integracje kończą jako nocne zadanie CSV i osoba, która „to sprawdza”.
Osiem poniższych kryteriów uporządkowano według tego, jak kosztowne jest ich obejście. Brakującej idempotencji nie da się na przykład naprawić po stronie klienta; zgrubny limit zapytań — tak.
Tabela oceny
Środkowej kolumny proszę używać jako pytania do każdego dostawcy; prawej — do oceny odpowiedzi.
| Kryterium | O co zapytać | Jak wygląda dobra odpowiedź |
|---|---|---|
| Uwierzytelnianie i najemca | Jak żądanie się identyfikuje i skąd serwer wie, której firmy dotyczy? | Sekret Bearer związany z dokładnie jedną firmą w chwili wydania; najemca nigdy nie pochodzi z nagłówka ani ścieżki kontrolowanej przez wywołującego; wywołanie, które mówi, do której firmy należy klucz. |
| Zakresy | Czy klucz można ograniczyć do odczytu albo do jednego typu obiektu? | Nazwane zakresy dla każdego obiektu i kierunku (odczyt / zapis), sprawdzane po stronie serwera, przy czym odczyt nie implikuje zapisu. |
| Idempotencja | Co się dzieje, gdy ponawiam POST, na który nigdy nie otrzymałem odpowiedzi? | Nagłówek Idempotency-Key; ten sam klucz i treść zwraca pierwotny wynik; ten sam klucz z inną treścią jest odrzucany; udokumentowany czas życia klucza. |
| Webhooki | Jak dowiem się, że faktura została opłacona, bez odpytywania? | Podpisane dostawy (HMAC ze znacznika czasu i surowej treści), identyfikator zdarzenia do deduplikacji, ponowienia z udokumentowaną liczbą, wyłącznie HTTPS, bez podążania za przekierowaniami. |
| Limity zapytań | Ile wywołań, jak mierzonych i co wraca, gdy je przekroczę? | Określony budżet i tempo uzupełniania na klucz; 429 z Retry-After; liczba, a nie „fair use”. |
| Sandbox | Gdzie mogę testować bez dotykania prawdziwych ksiąg? | Poświadczenia testowe, które używają tego samego API z tą samą walidacją; wyraźne oddzielenie od danych produkcyjnych. |
| Błędy i wersjonowanie | Jak wygląda niepowodzenie i co obiecuje wersja? | JSON z kodem czytelnym maszynowo i zdaniem dla człowieka; wersja w ścieżce; określona reguła, co może się zmienić w ramach wersji. |
| MCP dla asystentów | Czy asystent AI może czytać księgi i czego nie może zrobić? | Serwer MCP z tym samym kluczem i zakresami; narzędzia odczytu plus narzędzia szkiców; brak narzędzia, które wystawia dokumenty, wysyła pocztę, przesuwa pieniądze lub zmienia ustawienia. |
Trzy kryteria bardziej szczegółowo
Idempotencja to ta, której nie da się dołożyć później
Każda sieć w końcu gubi jakąś odpowiedź. Projekt IETF dla tego nagłówka opisuje jego cel: „uczynić nieidempotentne metody HTTP, takie jak POST czy PATCH, odpornymi na błędy”. Projekt wygasł, nie stając się RFC, ale konwencja, którą dokumentuje, jest tym, czego używa większość API płatniczych i księgowych. Jeśli API dostawcy jej nie ma, jedyne Państwa opcje to odpytywanie przed każdym zapisem (wyścig) albo akceptacja sporadycznych zduplikowanych klientów i faktur. Żadna z nich nie przetrwa dobrze audytu.
Webhooki: te same zasady co u Stripe
Wytyczne Stripe dotyczące webhooków stały się faktycznym standardem i są dobrą miarą dla każdego API księgowego: podpisy, aby „zweryfikować, że zdarzenia webhook pochodzą” od nadawcy, tolerancja duplikatów, ponieważ punkty końcowe „mogą sporadycznie otrzymać to samo zdarzenie więcej niż raz”, brak gwarantowanej kolejności oraz szybkie 2xx przed jakimkolwiek cięższym przetwarzaniem. Proszę zapytać dostawcę, czy jego dostawy niosą podpis, znacznik czasu i identyfikator zdarzenia — oraz czy podpis jest obliczany z surowej treści, ponieważ podpisu z ponownie zserializowanego JSON nie da się wiarygodnie zweryfikować.
MCP: dużo czytać, trochę przygotowywać, niczego nie wyzwalać
Model Context Protocol to „otwarty protokół, który umożliwia płynną integrację między aplikacjami LLM a zewnętrznymi źródłami danych i narzędziami”, używający komunikatów JSON-RPC 2.0 między hostami, klientami i serwerami. Jego specyfikacja mówi wprost, że narzędzia „reprezentują wykonanie dowolnego kodu i muszą być traktowane z należytą ostrożnością” oraz że „hosty muszą uzyskać wyraźną zgodę użytkownika przed wywołaniem jakiegokolwiek narzędzia”. Dla księgi rachunkowej przekłada się to na prosty test: proszę wypisać narzędzia i sprawdzić, czy żadne z nich nie może wystawić faktury, wysłać dokumentu, przesunąć pieniędzy ani zmienić ustawienia. Asystent, który potrafi odpowiedzieć „kto zalega z płatnością?” i przygotować szkic faktury do przeglądu przez osobę, jest użyteczny; ten, który może ją wystawić, jest obciążeniem.
Jak KRONENWERK odpowiada na każde kryterium
Poniższe liczby są tymi, które API egzekwuje dziś; dokumentacja referencyjna znajduje się w dokumentacji dla programistów. API, webhooki, serwer MCP i katalog integracji są częścią planu Enterprise — zob. plany. Obsługiwane z ograniczeniami
| Kryterium | KRONENWERK |
|---|---|
| Uwierzytelnianie i najemca | Klucz API Bearer z prefiksem greif_live_ lub greif_test_, pod adresem https://kronenwerk.org/api/extern/v1. Jedna firma na klucz, ustalona przy wydaniu; żaden nagłówek ani ścieżka nie wybiera firmy. GET /me zwraca firmę i zakresy. Przechowywany jest wyłącznie skrót klucza; utracony klucz jest zastępowany, nie odzyskiwany. Zob. uwierzytelnianie. |
| Zakresy | customers:read, customers:write, invoices:read, invoices:write, transactions:read, transactions:write, reports:read, companies:read. Odczyt i zapis są osobnymi uprawnieniami. |
| Idempotencja | Idempotency-Key wymagany przy każdym POST. Ten sam klucz i treść: pierwotny rekord; ten sam klucz i inna treść: odrzucenie z 409 i kodem IDEMPOTENZ_KONFLIKT; klucze żyją 24 godziny. Zob. idempotencja. |
| Webhooki | Zdarzenia invoice.issued, invoice.paid, invoice.cancelled, purchase.recorded, payment.recorded. Nagłówki KRONENWERK-Signature (t=…,v1=…, HMAC-SHA256 z t.raw_body, tolerancja 5 minut), KRONENWERK-Event-Id, KRONENWERK-Event, KRONENWERK-Delivery, KRONENWERK-Attempt, Idempotency-Key. Wyłącznie HTTPS, ponawiane do przyjęcia, bez podążania za przekierowaniami. Zob. webhooki. |
| Limity zapytań | Budżet 240 zapytań na klucz, uzupełniany w sposób ciągły w tempie około dwóch na sekundę. Przekroczenie zwraca 429 z Retry-After i kodem ZU_VIELE_ANFRAGEN. Zob. limity. |
| Sandbox | Klucz greif_test_ działa na tym samym API w trybie testowym dla firmy, która go utworzyła. Nie ma osobnego hosta sandbox. |
| Błędy i wersjonowanie | Błędy to JSON z kodem maszynowym i zdaniem, np. {"fehler": "…", "code": "NICHT_GEFUNDEN"}; kod jest częścią kontraktu, zdanie może zostać przeredagowane. Wersja jest w ścieżce (/v1); w ramach wersji pola mogą być dodawane, ale nie usuwane ani zmieniane co do typu, a kody zachowują znaczenie. Zob. błędy. |
| MCP | Serwer pod /api/extern/mcp, Streamable HTTP, ten sam klucz API. Narzędzia odczytu: get_customer, search_customers, get_invoice, list_invoices, get_transaction, list_transactions, list_receivables, list_payables, get_profit_and_loss, get_balance_sheet, get_business_attention. Narzędzia szkiców: create_invoice_draft, create_transaction, add_transaction_note. Żadne narzędzie nie wystawia faktury, nie wysyła poczty, nie przesuwa pieniędzy ani nie zmienia ustawień. Zob. MCP. |
Pełna lista punktów końcowych jest celowo krótka: GET /me, GET /customers, GET /customers/{id}, POST /customers, GET /invoices, GET /invoices/{number}, POST /invoices/drafts, GET /transactions, POST /transactions, GET /reports/outstanding. Żądanie i jego odrzucenie wyglądają tak:
GET /api/extern/v1/invoices?status=OPEN&size=1 HTTP/1.1
Host: kronenwerk.org
Authorization: Bearer greif_live_…
HTTP/1.1 200 OK
Content-Type: application/json
{"data":[{"number":"R-2026-0001","issuedOn":"2026-04-02","buyer":"Kellermann GmbH",
"currency":"EUR","gross":{"minor":105910,"currency":"EUR"},
"outstanding":{"minor":105910,"currency":"EUR"},"paymentState":"OPEN","overdue":false}],
"page":0,"size":1,"total":1,"more":false}HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
{"fehler":"…","code":"ZU_VIELE_ANFRAGEN"}API jest opisane prozą na stronie API księgowego; przegląd bezpieczeństwa znajduje się na stronie bezpieczeństwo dla programistów; szersza ocena dla firm europejskich — formaty, VAT, języki — na stronie czego potrzebuje europejska firma.
Najczęściej zadawane pytania
Czy klucz API wystarczy, czy powinienem nalegać na OAuth?
Dla integracji serwer–serwer, w której kontrolują Państwo oba końce, klucz z zakresami związany z jedną firmą jest prostszy i nie mniej bezpieczny. OAuth ma znaczenie, gdy strony trzecie działają w imieniu wielu Państwa użytkowników; nie jest tak w przypadku firmy integrującej własną aplikację z własną księgą.
Jaki limit zapytań jest rozsądny dla API księgowego?
Wystarczający na szczyt na koniec miesiąca i równomierny strumień poza nim. Budżet KRONENWERK — 240 zapytań uzupełnianych w tempie około dwóch na sekundę — pasuje do tego wzorca; ważniejsze jest to, że limit jest określony i że 429 niesie Retry-After.
Dlaczego KRONENWERK nie pozwala API wystawiać faktur?
Ponieważ wystawienie nadaje numer prawny, generuje e-fakturę i sprawdza numer VAT; produkt trzyma ten krok za walidacją i osobą. Szkice przez API, wystawianie w produkcie.
Czy mogę korzystać z sandboxa bez płatnego planu?
Klucz testowy tworzy się wewnątrz firmy w planie Enterprise; nie ma osobnego publicznego hosta sandbox. Zob. plany.
Czy serwer MCP daje asystentowi dostęp do zapisu w moich księgach?
Tylko do szkiców i notatek: może przygotować szkic faktury lub transakcję do przeglądu przez osobę. Nie może niczego wystawić, wysłać, opłacić ani przekonfigurować.