Jak połączyć aplikację z programem księgowym: CSV, integracje, API, MCP

Istnieją cztery sposoby przekazania danych z własnej aplikacji do programu księgowego: eksport pliku CSV i jego import, gotowa integracja zbudowana przez dostawcę, wywołanie publicznego API z własnego kodu albo praca asystenta AI przez serwer MCP. Dla wszystkiego, co ma działać codziennie, uczciwym wyborem jest API, a dobre połączenie przez API sprowadza się do pięciu decyzji: co synchronizować, w którym kierunku, jak zabezpieczyć ponowne próby (idempotencja), jak dowiadywać się o zmianach (webhooki) i gdzie przechowywać klucz.

Cztery opcje i kiedy każda z nich wystarcza

CSV wystarczy do przekazywania danych księgowemu raz na kwartał. Gotowa integracja wystarczy, gdy dwa produkty, z których Państwo korzystają, są akurat tymi dwoma, które dostawca ze sobą połączył. API jest potrzebne wtedy, gdy dane powstają we własnym systemie i muszą docierać w komplecie, codziennie, bez udziału człowieka. MCP to piąta warstwa nad API dla osób, które wolą zadawać asystentowi pytania niż pisać kod.

Opcje nie wykluczają się wzajemnie. Częsty układ to API dla codziennego przepływu, MCP dla właściciela firmy, który pyta „kto jeszcze nie zapłacił?”, oraz eksport CSV na koniec roku do programu księgowego biura rachunkowego.

Co synchronizować: klientów, faktury, płatności — w tej kolejności

Synchronizujcie Państwo obiekty, których księga potrzebuje, aby wystawić poprawną fakturę i dopasować płatność — i nic więcej. W praktyce są to trzy obiekty powiązane zależnością: klient musi istnieć, zanim faktura będzie mogła się do niego odwołać, a faktura musi istnieć, zanim płatność będzie mogła ją rozliczyć.

Klienci

Nazwa, adres, kraj, numer VAT, status przedsiębiorcy lub konsumenta oraz Państwa własny identyfikator zewnętrzny. To kraj i status VAT decydują o traktowaniu podatkowym; należy je ustalić poprawnie przy tworzeniu klienta, a nie dopiero na fakturze.

Faktury

Pozycje z opisem, ilością, ceną jednostkową i rodzajem świadczenia; waluta; termin płatności; odniesienie do Państwa zamówienia lub subskrypcji. Nie należy przesyłać stawki podatku — proszę przesłać fakty i pozwolić księdze zdecydować, w przeciwnym razie zaimplementują Państwo prawo o VAT po raz drugi we własnej aplikacji.

Płatności

Kwota, data, waluta oraz faktura lub faktury, które płatność rozlicza. Jeśli w grę wchodzi operator płatności, to jego identyfikator transakcji jest kluczem, który później pozwala uzgodnić wypłatę.

Kierunek ma znaczenie. Klienci i faktury zwykle płyną z Państwa aplikacji do księgi. Status płatności często wraca w drugą stronę — księga widzi wyciąg bankowy, a Państwa aplikacja chce wiedzieć, że faktura została opłacona. Raporty (należności otwarte, rachunek zysków i strat) płyną wyłącznie z powrotem. Dla każdego obiektu proszę zdecydować, który system jest źródłem prawdy, i nigdy nie zapisywać tego samego pola z obu stron.

Czego nie synchronizować: wewnętrznych zdarzeń produktu (logowania, użycie funkcji), roboczych zamówień, które być może nigdy nie zostaną zafakturowane, oraz wszystkiego, na czym księga nie może nic zrobić. Każdy obiekt, który Państwo przesyłają, to obiekt, którego spójność trzeba będzie utrzymywać.

Idempotencja: odpowiedź, która nigdy nie dociera

Połączenie zrywa się po tym, jak księga utworzyła klienta, ale zanim Państwa aplikacja otrzymała odpowiedź. Bez zabezpieczenia albo tracą Państwo rekord, albo tworzą go dwukrotnie, a zduplikowany klient wychodzi na jaw tygodnie później, gdy faktura trafia do niewłaściwej kopii. Rozwiązaniem jest klucz idempotencji: wartość wybierana przez Państwa dla każdego zamierzonego zapisu, wysyłana w nagłówku, która pozwala serwerowi rozpoznać powtórzenie.

Internet-Draft IETF dotyczący tego nagłówka wprost określa jego cel: „The HTTP Idempotency-Key request header field can be used to make non-idempotent HTTP methods such as POST or PATCH fault-tolerant” (nagłówek żądania HTTP Idempotency-Key może służyć do uodpornienia na błędy nieidempotentnych metod HTTP, takich jak POST czy PATCH). Projekt wygasł, nie stając się RFC, ale wzorzec jest branżową konwencją, a nazwa nagłówka jest tą, której używa większość API. Reguły, dzięki którym działa to po stronie serwera:

1. Pierwsze żądanie z danym kluczem wykonuje pracę i zapisuje wynik.
2. Powtórzenie z tym samym kluczem i tą samą treścią zwraca zapisany wynik — ten sam rekord, nie nowy.
3. Powtórzenie z tym samym kluczem, ale inną treścią jest odrzucane, ponieważ klucz reprezentuje jedną intencję.
4. Klucze wygasają po pewnym oknie czasowym, po którym ta sama wartość liczy się jako nowa praca.

Po stronie klienta: klucz należy wygenerować w chwili powstania intencji (UUID zapisany razem z własnym wierszem zamówienia), a nie w chwili wysłania żądania, tak aby ponowna próba po awarii użyła go ponownie. Ponawiać z wykładniczym odstępem przy błędach sieci i przy 5xx; nie ponawiać przy 4xx z wyjątkiem 429.

Webhooki: dowiadywać się o zmianach bez odpytywania

Webhook to żądanie HTTP, które program księgowy wysyła na Państwa adres URL, gdy coś się wydarzy — wystawiono fakturę, zarejestrowano płatność. Zastępuje odpytywanie (polling), ale niesie trzy obowiązki: weryfikować podpis, spodziewać się duplikatów i odpowiadać szybko.

Wytyczne Stripe są punktem odniesienia znanym większości programistów i mają zastosowanie do każdego dostawcy: „Always verify that webhook events originate from Stripe before acting on them” (zawsze weryfikuj, że zdarzenia webhooka pochodzą od Stripe, zanim na nie zareagujesz); „webhook endpoints might occasionally receive the same event more than once” (punkty końcowe webhooków mogą sporadycznie otrzymać to samo zdarzenie więcej niż raz), przed czym chronią się Państwo, „logging the event IDs you've processed” (logując identyfikatory przetworzonych zdarzeń); a Państwa punkt końcowy „must quickly return a successful status code (2xx) before any complex logic that could cause a timeout” (musi szybko zwrócić kod powodzenia 2xx, zanim wykona jakąkolwiek złożoną logikę, która mogłaby spowodować przekroczenie limitu czasu). Stripe zaznacza też, że „doesn't guarantee the delivery of events in the order that they're generated” (nie gwarantuje dostarczania zdarzeń w kolejności ich powstania) — dlatego każde zdarzenie należy traktować jako wskaźnik i pobrać aktualny stan, jeśli kolejność ma znaczenie.

Weryfikacja podpisu na ogół przebiega według jednego wzorca: nagłówek ze znacznikiem czasu i HMAC obliczonym nad timestamp.raw_body; odrzucić, jeśli znacznik czasu leży poza oknem tolerancji (ochrona przed powtórzeniem), obliczyć ponownie HMAC z sekretem punktu końcowego nad surowymi bajtami i porównać w stałym czasie. Frameworki, które parsują i ponownie serializują JSON, zanim odczytają Państwo treść, psują ten mechanizm; należy czytać surową treść.

Bezpieczne przechowywanie klucza

Klucz API do księgowości może odczytać każdego klienta i każdą fakturę firmy oraz tworzyć wersje robocze. Należy traktować go jak hasło do bazy danych: przechowywać w menedżerze sekretów lub zmiennej środowiskowej, nigdy w repozytorium kodu ani w aplikacji mobilnej, i nadawać mu tylko te zakresy uprawnień, których integracja używa.

• Najmniejszy zakres. Panel, który tylko odczytuje należności, potrzebuje zakresu odczytu, nie zapisu. Odczyt i zapis to osobne uprawnienia.
• Jeden klucz na integrację. Aby jeden można było unieważnić, nie psując pozostałych, i aby ścieżka audytu mówiła, który system co zrobił.
• Klucze testowe w środowisku testowym, klucze produkcyjne w produkcji. Prefiks klucza powinien sprawiać, że środowisko jest oczywiste już w linii logu.
• Rotacja. Dostawca, który przechowuje tylko skrót klucza, nie może pokazać go Państwu ponownie — i to jest poprawny projekt. Rotację należy zaplanować od początku: wydać nowy klucz, przełączyć, unieważnić stary.
• Sekrety webhooków też są kluczami. To samo przechowywanie, ta sama rotacja.

Specyfikacja MCP dodaje uwagę o asystentach: „Hosts must obtain explicit user consent before invoking any tool” (hosty muszą uzyskać wyraźną zgodę użytkownika przed wywołaniem jakiegokolwiek narzędzia), a narzędzia „represent arbitrary code execution and must be treated with appropriate caution” (oznaczają wykonanie dowolnego kodu i muszą być traktowane z odpowiednią ostrożnością). Serwer MCP przed księgą rachunkową powinien zatem udostępniać odczyty i przygotowanie, a nie działania nieodwracalne, a odpowiedzialność pozostaje przy osobie przy klawiaturze.

Jak KRONENWERK to obsługuje

KRONENWERK oferuje wszystkie cztery ścieżki; API, webhooki, serwer MCP i katalog integracji są częścią planu Enterprise (zob. plany). OBSŁUGIWANE Z OGRANICZENIAMI

• API. https://kronenwerk.org/api/extern/v1, klucz API typu Bearer z prefiksem greif_live_ lub greif_test_, zakresy takie jak customers:write, invoices:write, transactions:write i reports:read. Punkty końcowe dla klientów (GET/POST /customers), faktur (GET /invoices, POST /invoices/drafts), transakcji (GET/POST /transactions) oraz GET /reports/outstanding. Jedna firma na klucz; GET /me ją wskazuje. KRONENWERK przechowuje wyłącznie skrót klucza; klucze unieważnia się lub rotuje na ekranie dla programistów.
• Idempotencja. Idempotency-Key jest wymagany przy każdym POST. Ten sam klucz i treść: wraca ten sam rekord; ten sam klucz i inna treść: odmowa; klucze żyją 24 godziny. Szczegóły na stronie idempotencja.
• Webhooki. Zdarzenia invoice.issued, invoice.paid, invoice.cancelled, purchase.recorded, payment.recorded. Każde dostarczenie niesie KRONENWERK-Signature (t=<sekundy uniksowe>,v1=<szesnastkowy HMAC-SHA256 nad t.raw_body>, tolerancja 5 minut), KRONENWERK-Event-Id, KRONENWERK-Event, KRONENWERK-Delivery, KRONENWERK-Attempt oraz Idempotency-Key do deduplikacji. Wyłącznie HTTPS, ponowne próby aż do przyjęcia, przekierowania nie są śledzone. Zob. webhooki.
• MCP. Serwer pod adresem /api/extern/mcp (Streamable HTTP, ten sam klucz) z narzędziami odczytu, takimi jak list_receivables i get_profit_and_loss, oraz narzędziami roboczymi 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ń.
• Limit żądań. Budżet 240 żądań na klucz, uzupełniany w sposób ciągły (około dwóch na sekundę); po przekroczeniu 429 z Retry-After.

POST /api/extern/v1/customers HTTP/1.1
Host: kronenwerk.org
Authorization: Bearer greif_test_…
Idempotency-Key: 6f1c2a8e-4b3d-4a21-9d77-0c5e1f9b2a44
Content-Type: application/json

{"name": "Example SRL", "country": "BE", "vatId": "BE0123456789", "email": "ap@example.be"}

Rozpisany przykład trzech przepływów znajduje się na stronie podłączenie SaaS do księgowości; pełny zakres opisano na stronie API księgowe oraz w dokumentacji referencyjnej.