Jak zintegrować API chmurowego systemu księgowego z platformą SaaS

Praktyczny przewodnik po budowie wielodostępnej integracji księgowej, która radzi sobie z OAuth, webhookami, przepisami podatkowymi i uzgadnianiem danych bez uszkadzania księgi głównej.

Większość zespołów, które postanawiają "dodać księgowość" do swojego produktu SaaS, zaczyna od podpięcia klienta HTTP do endpointu dostawcy i przesłania faktury. To działa w demo. Przestaje działać za pierwszym razem, gdy klient połączy dwie organizacje księgowe, gdy webhook dotrze dwukrotnie, albo gdy token odświeżania (refresh token) ulegnie rotacji i zgubi się w trakcie żądania. Trwała wersja tego zadania to nie klient HTTP. To warstwa integracyjna.

Ta warstwa musi zarządzać połączeniami dzierżawców (tenants), przechowywaniem i rotacją tokenów, regułami księgowymi specyficznymi dla danego dostawcy, mapowaniem rekordów, synchronizacją początkową i przyrostową, odbieraniem webhooków z mechanizmem ponownych prób (retries) i deduplikacją, limitami żądań (rate limits), wersjonowaniem oraz śladem audytowym, który Twój zespół wsparcia może przeczytać o 2 w nocy. Ten artykuł przeprowadza przez tę architekturę i decyzje, które mają największe znaczenie.

Przydatny model myślowy:

Produkt SaaS → usługa integracji księgowej → adapter dostawcy (lub ujednolicone API) → asynchroniczna synchronizacja i uzgadnianie danych

System księgowy pozostaje systemem źródłowym (system of record) dla obiektów księgi głównej (ledger): kont, kodów podatkowych, zaksięgowanych transakcji i wpisów w dzienniku. Twoja platforma SaaS utrzymuje stabilne identyfikatory międzysystemowe, stan synchronizacji, metadane mapowania oraz operacyjny dziennik audytu.

Czego tak naprawdę dotyczy „API chmurowego systemu księgowego”

To wyrażenie zazwyczaj oznacza API hostowanej platformy księgowej, takiej jak QuickBooks Online, Xero, Sage, Zoho Books czy system regionalny. Może również oznaczać ujednolicone API księgowe (unified accounting API), które normalizuje wielu dostawców za pomocą jednego interfejsu.

Warto być precyzyjnym, ponieważ wdrożenie różni się w zależności od intencji. Odczytywanie faktur na potrzeby raportowania to nie to samo zadanie co tworzenie faktur na podstawie aktywności w SaaS, księgowanie rachunków, synchronizowanie klientów i produktów, zapisywanie wpisów w dzienniku czy przeprowadzanie prawdziwej dwukierunkowej synchronizacji. Zdecyduj, co dokładnie budujesz, zanim dotkniesz jakiegokolwiek endpointu.

Dla tego artykułu ważna jest jeszcze jedna dystynkcja. API płatności przesyła pieniądze. API bankowe pobiera dane o rachunkach. API fakturowe może tworzyć dokumenty bez ujawniania księgi głównej. Wbudowana księga główna (embedded ledger) to jeszcze coś innego: firma SaaS jest właścicielem samego silnika księgowego. To ostatnie podejście reprezentuje Nordlet. Zamiast łączyć Twój produkt z zewnętrzną księgowością klienta, Nordlet daje platformom i giełdom prawdziwą księgowość podwójną, niezmienną i gotową do audytu księgę główną, obsługę unijnego VAT-u oraz wypłaty bezpośrednio wewnątrz ich własnego produktu za pomocą projektu opartego na API ze zwtypowanymi zestawami SDK i webhookami. Jeśli jesteś marketplace'em decydującym się na integrację systemu księgowego klienta lub samodzielne prowadzenie ksiąg, to prawdziwy rozdroże, do którego jeszcze wrócimy.

Wielodostępność (multi-tenancy): zakresuj każde połączenie dwukrotnie

W produkcie SaaS jedna aplikacja łączy się z wieloma organizacjami klientów. Każde połączenie musi być ograniczone (scoped) zarówno przez dzierżawcę (tenant) w SaaS, jak i identyfikator organizacji u dostawcy, taki jak ID dzierżawcy Xero czy identyfikator realm w QuickBooks.

Nie opieraj kluczy połączeń wyłącznie na ID użytkownika OAuth. Jeden użytkownik może autoryzować kilka organizacji księgowych, a jedna organizacja może być ponownie łączona przez różnych użytkowników na przestrzeni czasu. Jeśli zrobisz to źle, w końcu zaksięgujesz fakturę jednego klienta w księgach innego, a po takim błędzie nie da się odzyskać danych ot tak.

Pierwsza decyzja architektoniczna: bezpośredni konektor, ujednolicone API czy wbudowana księga

Bezpośrednie integracje z dostawcami

Bezpośrednia integracja daje największą kontrolę: funkcje specyficzne dla dostawcy, pola niestandardowe, obsługę błędów, częstotliwość synchronizacji, retencję danych i strukturę kosztów. Cena za to jest realna. Każdy dostawca przynosi swój własny przepływ OAuth, schemat danych, specyficzne dziwactwa, limity żądań, zachowanie webhooków, certyfikację i ciągłe utrzymanie.

Ujednolicone API księgowe

Ujednolicone API oferuje jeden interfejs dla wielu systemów księgowych, normalizując takie encje jak klienci, faktury, dostawcy, konta, płatności i produkty. Może skrócić początkowy czas budowy. Nie likwiduje jednak złożoności integracji, a traktowanie go tak, jakby to robiło, jest powszechnym błędem.

Zanim podejmiesz zobowiązanie, zbadaj: którzy dostawcy i operacje są obsługiwani? Czy operacje zapisu działają, czy tylko odczyt? Czy zapisy są synchroniczne, czy kolejkowane? Czy pola specyficzne dla dostawcy są dostępne przez przekierowanie (passthrough)? Czy dane są buforowane i jak są świeże? Kto radzi sobie z awariami dostawcy i zmianami w API? Czy model cenowy opiera się na liczbie wywołań, połączonych kontach, rekordach, czy na opłacie platformowej? Czy możesz wyeksportować swoje mapowania i bezpiecznie się rozłączyć? „Ujednolicony” rzadko oznacza „tożsamy pod względem funkcji u każdego dostawcy”.

Wbudowana księga główna (embedded ledger)

Jeśli głównym problemem Twojej platformy jest prowadzenie księgowości dla Twoich użytkowników, a nie odzwierciedlanie jej w ich istniejących księgach, wbudowana księga zmienia całą kalkulację. Platformie e-commerce (marketplace) z tysiącami sprzedawców lub produktowi SaaS, który wymaga gotowej do audytu unijnej procedury VAT i zgodności z przepisami w poszczególnych krajach, lepiej służy posiadanie własnego silnika księgowego niż spinanie $N$ zewnętrznych konektorów. Na tym polega pozycjonowanie Nordlet: prawdziwa księgowość przez API, niezmienna podwójna księgowość, stawki VAT per kraj z walidacją VIES i generowaniem rejestru i.SAF, eksport SEPA oraz raporty w formacie XLSX, PDF lub JSON – wszystko wewnątrz Twojego produktu, a nie w zewnętrznym systemie płatności.

Zasada decyzyjna, której używam:

Sytuacja	Najlepszy wybór
Jeden dostawca księgowy dominuje w Twojej bazie klientów; kluczowe jest zachowanie specyficzne dla dostawcy	Bezpośredni konektor
Szeroki zasięgiem dostawców i czas wejścia na rynek są ważniejsze niż kontrola	Ujednolicone API
Jesteś platformą lub rynkiem, który musi prowadzić i posiadać księgi, z unijnym VAT-em i śladami audytu	Wbudowana księga główna (Nordlet)
Mieszana rzeczywistość	Hybryda: ujednolicone API dla typowych procesów, bezpośrednie konektory dla kluczowych dostawców

Zalecana architektura integracji

Izoluj integrację od głównej logiki biznesowej

Nie rozpraszaj wywołań dostawcy po całym module rozliczeń, zamówień, subskrypcji i raportowania. Zbuduj dedykowaną usługę integracyjną zawierającą adaptery dostawców, zarządzanie połączeniami OAuth, modele kanoniczne, mapowania identyfikatorów, zadania i kolejki synchronizacji, endpointy webhooków, obsługę ponownych prób oraz kolejek wiadomości niedostarczonych (dead-letter), dzienniki audytu i narzędzia do uzgadniania danych. Dzięki temu nazwy pól z Xero czy QuickBooks nie przenikną do Twojego modelu domeny.

Zdefiniuj wąski model kanoniczny

Modeluj tylko te przepływy pracy, które obsługujesz. Typowe obiekty: klient, produkt lub pozycja usługowa, faktura, pozycja faktury, płatność, nota korygowa, dostawca, konto, stawka podatkowa, waluta, wpis w dzienniku.

Zachowaj rozróżnienia wpływające na księgowość. Nie spłaszczaj stanu roboczego (draft) do zatwierdzonego (approved) lub zaksięgowanego (posted), kwot z podatkiem do kwot bez podatku, not korygujących do ujemnych faktur, alokacji płatności do samego istnienia płatności, ani numeru faktury widocznego dla klienta do ID obiektu u dostawcy. Każdy rekord powinien zawierać: ID w SaaS, ID u dostawcy, nazwę dostawcy i wersję API, wskaźnik źródła prawdy (source-of-truth), status, znaczniki czasu, czas ostatniej synchronizacji, odniesienie zewnętrzne oraz status błędu lub uzgodnienia.

Utrzymuj wyraźne tabele mapowań

Mapuj dzierżawcę SaaS na organizację księgową, klienta SaaS na kontakt dostawcy, produkt SaaS na pozycję lub konto dostawcy, fakturę SaaS na fakturę dostawcy, płatność SaaS na płatność dostawcy, kategorię podatkową na kod podatku oraz kategorię przychodów na konto w księdze głównej.

Nigdy nie używaj nazw ani adresów e-mail jako stałych identyfikatorów. Nazwy się zmieniają, duplikaty istnieją, a dwóch klientów może dzielić ten sam e-mail. Przechowuj niezmienne ID (immutable ID) od dostawcy i zachowaj oryginalne ID z SaaS.

Dodaj maszyny stanów (state machines)

Nadaj połączeniu wyraźne stany: niepołączone, autoryzacja w toku, połączone, oczekiwanie na synchronizację początkową, synchronizacja, poprawne, ograniczenie liczby żądań (rate limited), wymagana ponowna autoryzacja, dostawca niedostępny, rozłączone, trwały błąd. Rekordom nadaj własne stany: oczekujące, wysłane, potwierdzone, błąd z możliwością ponowienia, błąd wymagający interwencji użytkownika, uzgodnione, wykryty konflikt. Binarna flaga „połączone / niepołączone” nie mówi zespołowi wsparcia nic przydatnego.

OAuth i wdrażanie połączeń

Użyj przepływu kodu autoryzacji (authorization code flow). Klient kliknąć „Połącz”, Twój serwer tworzy krótkotrwałą transakcję autoryzacji, klient uwierzytelnia się u dostawcy i przyznaje uprawnienia (scopes), wymieniasz kod na tokeny, wykrywasz autoryzowaną organizację, zapisujesz połączenie przypisane do właściwego dzierżawcy i kolejkujesz synchronizację początkową.

Dokładnie zweryfikuj zwrotne wywołanie (callback): state względem transakcji po stronie serwera, dokładny adres URL przekierowania, wystawcę (issuer) dostawcy oraz kontekst dzierżawcy. RFC 9700, OAuth 2.0 Security Best Current Practice formalizuje obecne wytyczne: używaj PKCE z przepływami opartymi na kodzie autoryzacji, unikaj przepływów implicit i password oraz stosuj dokładne dopasowanie URI przekierowania.

Żądaj uprawnień o najmniejszych koniecznych przywilejach (least-privilege scopes). Tam, gdzie nie musisz niczego zapisywać, używaj dostępu tylko do odczytu. Modele uprawnień się zmieniają, więc nie kopiuj starych przykładów. Dokumentacja OAuth Xero wskazuje, że szerokie uprawnienia księgowe są zastępowane ziarnistymi (granular), a nowym aplikacjom przypisuje się uprawnienia ziarniste od marca 2026 roku, podczas gdy szerokie uprawnienia mają pozostać dostępne do września 2027 roku.

Przechowuj tokeny wyłącznie po stronie serwera. Nigdy nie ujawniaj ich w skryptach JavaScript w przeglądarce, klientach mobilnych, logach frontendu, analityce ani w komunikatach o błędach dla klientów. Szyfruj w spoczynku, maskuj w logach i przechowuj metadane dla każdego połączenia: zaszyfrowane tokeny dostępu i odświeżania, czas wygaśnięcia, ID organizacji u dostawcy, przyznane uprawnienia, czas wydania, czas ostatniego udanego odświeżenia oraz status unieważnienia.

Rotacja tokenów odświeżania to moment, w którym produkcja się psuje

Odświeżenie może zwrócić nowy token odświeżania (refresh token). Musisz zapisać nową wartość atomowo, w przeciwnym razie odetcesz klientowi dostęp. Zgodnie z FAQ dla deweloperów Xero, każde odświeżenie generuje nowy token odświeżania, tokeny te ważne są do 60 dni, a w przypadku utraty odpowiedzi obowiązuje 30-minutowy okres karencji na ponowną próbę z dotychczasowym tokenem. QuickBooks Online instruuje deweloperów, aby przechowywali najnowszy token odświeżania z najnowszej odpowiedzi: tokeny odświeżania zachowują ważność do 100 dni, a ich wartość może rotować nawet co 24 godziny.

W praktyce: użyj blokady odświeżania dla każdego połączenia, wymieniaj token odświeżania atomowo, obsługuj chwilowe awarie endpointu tokenów za pomocą ponownych prób, eksponuj czytelny stan ponownej autoryzacji i nigdy nie odświeżaj tokena przy każdym wywołaniu API, dopóki obecny token dostępu jest ważny.

Synchronizacja początkowa

Uruchom synchronizację początkową jako zadanie w tle (background job). Nie blokuj na niej wywołania zwrotnego OAuth ani interfejsu użytkownika.

Solidna sekwencja: pobierz metadane organizacji, pobierz konta, stawki podatkowe, waluty, kontakty i pozycje, zapisz ID dostawcy i mapowania, zaimportuj tylko to okno historyczne, którego produkt potrzebuje, zakolejkuj zależne rekordy w kolejności zależności, zarejestruj punkt kontrolny (checkpoint) i oznacz połączenie jako poprawne dopiero po walidacji.

Kolejność zależności ma znaczenie. Faktura może wymagać wcześniejszego istnienia kontaktu, pozycji, konta przychodowego, kodu podatkowego i waluty. Nie twórz ślepo duplikatów. Dopasowuj po zapisanym identyfikatorze zewnętrznym, referencji dostarczonej przez klienta, zdefiniowanej regule dopasowania lub kroku jawnego wyboru przez użytkownika w przypadkach niejednoznacznych.

Synchronizacja przyrostowa

Traktuj webhooki jako sygnały, a nie miarodajne rekordy

Webhook zazwyczaj informuje, że coś się zmieniło. Zweryfikuj sygnaturę, zarejestruj surowe zdarzenie, szybko zwróć wymaganą odpowiedź o sukcesie, zdeduplikuj, zakolejkuj dodatkowe pobieranie, pobierz aktualny obiekt od dostawcy, zastosuj aktualizację transakcyjnie, zaktualizuj punkt kontrolny i przekieruj błędy do ponowienia lub uzgodnienia. To podejście radzi sobie z niekompletnymi ładunkami danych i zdarzeniami w niewłaściwej kolejności.

Zasady dostawców są różne, więc nie obiecywano jednego uniwersalnego zachowania. Webhooki Xero zawierają sygnaturę HMAC-SHA256 w nagłówku x-xero-signature, wymagają HTTPS, ponawiają próby z malejącą częstotliwością przez maksymalnie 24 godziny, mogą zostać wyłączone po powtarzających się błędach i mogą przechowywać zdarzenia do 31 dni do ponownego odtworzenia po awarii. QuickBooks Online weryfikuje dane za pomocą HMAC-SHA256 i tokena weryfikacyjnego, oczekuje odpowiedzi HTTP 200 w ciągu trzech sekund i ponawia próby według stałego harmonogramu, który ostatecznie przechodzi w interwały sześciogodzinne, przy czym Intuit zaleca przetwarzanie asynchroniczne.

Deduplikacja i idempotencja

Dostarczenie co najmniej raz (at-least-once) jest normą. Oczekuj zduplikowanych webhooków, ponownych prób po przekroczeniu limitu czasu, kiedy zapis faktycznie się powiódł, zdarzeń w zmienionej kolejności i wielokrotnych kliknięć użytkownika. Używaj ID zdarzenia dostawcy, jeśli jest dostępne, unikalnego klucza zdarzenia w trwałym magazynie danych, identyfikatora operacji generowanego przed każdym zapisem, ograniczeń unikalności w bazie danych, semantyki upsert oraz zapytania uzgadniającego po niejednoznacznych przekroczeniach czasu.

Nie zakładaj, że każde API księgowe oferuje natywne klucze idempotencji. Jeśli dostawca ich nie oferuje, przechowuj wewnętrzny klucz operacji i sprawdź, czy oczekiwany obiekt zdalny już istnieje, zanim ponowisz próbę. Wzorce zaczerpnięte z idempotentnych żądań Stripe i ogólne wytyczne dotyczące idempotencji webhooków sprawdzają się tutaj doskonale.

Polling i wykrywanie zmian

Połącz webhooki z okresowym odpytywaniem (pollingiem). Webhooki bywają wyłączane, opóźnione, gubione z powodu błędów konfiguracji lub ograniczone do wybranych obiektów. Xero obsługuje nagłówek If-Modified-Since dla zmian po wskazanym znaczniku czasu UTC, ale dokumentacja ostrzega, że nie każda zmiana aktualizuje pole UpdatedDateUTC, więc niektóre częściowo opłacone transakcje i pola kontaktów nie pojawią się przy użyciu tego filtra. Mechanizm Change Data Capture w QuickBooks Online śledzi zmiany z ostatnich 30 dni, ogranicza odpowiedzi do 1000 obiektów, zwraca usunięte encje ze statusem Deleted i działa najlepiej przy krótszych oknach odpytywania.

Przechowuj punkt kontrolny dla każdego dostawcy i dzierżawcy oraz używaj okien zachodzących na siebie (overlap windows). Żądaj zmian sprzed ostatniego punktu kontrolnego, a następnie zdeduplikuj dane według ID dostawcy i wersji modyfikacji. To chroni przed rozbieżnością zegarów i częściowymi awariami.

Integralność danych specyficzna dla księgowości

To jest element, który odróżnia działającą integrację od integracji budzącej zaufanie.

Zachowanie podatkowe nie jest wymienne. Dokumentacja Xero zauważa, że faktury, noty korygujące i zamówienia zakupu domyślnie zawierają kwoty netto (tax-exclusive), gdy pole LineAmountTypes nie jest ustawione, paragony i transakcje bankowe domyślnie zawierają podatki w kwocie brutto (tax-inclusive), a wpisy manualne domyślnie nie mają podatku. Używaj pola TaxType, a nie nazwy stawki podatkowej. Nigdy nie zakładaj, że „20% VAT” jednoznacznie identyfikuje kod podatku; stawka może różnić się w zależności od kraju, typu transakcji, daty wejścia w życie i konfiguracji organizacji. W tym obszarze ręczna obsługa unijnego VAT-u w wielu krajach staje się kosztowna, i właśnie tam wbudowana księga z wbudowaną zgodnością z przepisami krajowymi zarabia na swoje istnienie.

Do obliczeń pieniężnych używaj liczb dziesiętnych o stałej precyzji, nigdy zmiennoprzecinkowych binarnych. Przechowuj kod waluty i precyzję, kwotę jednostkową, ilość, rabat, kwotę podatku, kwotę netto, brutto oraz kurs wymiany. Jasno zdecyduj, czy wysyłasz kwoty na poziomie pozycji i pozwalasz dostawcy obliczać sumy, czy wysyłasz wstępnie obliczoną sumę. Łączenie obu podejść prowadzi do rozbieżności zaokrągleń, które Twój księgowy z pewnością wykryje.

Odnnoś się do kont w księdze głównej za pomocą identyfikatora lub kodu dostawcy, a nie nazwy wyświetlanej. Przed zapisem zweryfikuj, czy konta, kody podatkowe, klienci, pozycje i waluta są aktywne i obsługiwane. Błąd zapisu faktury to zazwyczaj problem z mapowaniem lub konfiguracją, a nie chwilowy błąd API, więc interfejs użytkownika powinien wyjaśniać sposób naprawy, zamiast pokazywać komunikat „synchronizacja nie powiodła się”.

Nie zakładaj tożsamości obiektów. „Płatność” może oznaczać wpływ, alokację, depozyt, transakcję bankową lub wpis w dzienniku. „Subskrypcja” w SaaS może nie mapować się czysto na „fakturę” w księgowości. Zdefiniuj zdarzenie księgowe, które chcesz odwzorować, zanim wybierzesz obiekt API. Zobacz dokumentację płatności Xero, aby zobaczyć, jak jeden dostawca modeluje te kwestie.

Limity żądań (rate limits) i wersjonowanie

Limity są zazwyczaj przypisane do dzierżawcy, organizacji, aplikacji lub ich kombinacji. Zgodnie z FAQ dotyczącym limitów Xero: pięć żądań współbieżnych na dzierżawcę, 60 na minutę na dzierżawcę, 5000 dziennie na dzierżawcę oraz 10 000 na minutę w całej aplikacji, z nagłówkami pozostałego limitu i nagłówkiem Retry-After przy odpowiedziach 429. QuickBooks Online dokumentuje 500 żądań na minutę i 10 na sekundę na identyfikador realm, z endpointem wsadowym obsługującym do 30 operacji na żądanie.

Zbuduj ograniczanie liczby żądań dla każdego dzierżawcy (per-tenant rate limiting), globalne ograniczanie przepustowości, wykładnicze wycofywanie się z losowym opóźnieniem (exponential backoff with jitter), poszanowanie nagłówka Retry-After, ograniczoną współbieżność, paginację oraz metryki dotyczące błędów 429 i pozostałego limitu. Nie używaj nieograniczonej równoległości przy imporcie; jeden duży klient może zagłodzić każde inne zadanie dla tego dzierżawcy.

Przypisuj na stałe lub świadomie zarządzaj wersjami API. QuickBooks Online domyślnie używa wersji mniejszej (minor version) 75, gdy żadna nie jest określona. Centralizuj wersje w konfiguracji, przeprowadzaj testy kontraktowe na piaskownicach (sandboxes), monitoruj informacje o wydaniach (release notes) i traktuj nieznane pola w odpowiedziach jako kompatybilne wstecz. Środowiska piaskownicowe nie odwzorują każdego warunku produkcyjnego, dlatego przed uruchomieniem przetestuj rozłączenie, ponowne połączenie, cofnięcie zgody, wygaśnięcie tokenów, limity żądań i edycje po stronie dostawcy.

Co zbudowałbym w pierwszej kolejności

Gdybyśmy zaczynali to jutro, kolejność powinna być następująca:

Zdefiniuj dokładny przepływ księgowy: które zdarzenia i obiekty odczytujesz lub zapisujesz.
Wybierz strategię dostawcy: bezpośrednia, ujednolicona, wbudowana lub hybrydowa.
Zbuduj model połączeń powiązany z dzierżawcem, zawierający ID organizacji dostawcy, uprawnienia, status i metadane tokenów.
Zaimplementuj OAuth przy użyciu przepływu kodu autoryzacji, PKCE, walidacji stanu, uprawnień o najmniejszych uprawnieniach i przechowywania tokenów po stronie serwera.
Zbuduj jeden adapter dostawcy za stabilnym interfejsem wewnętrznym.
Utwórz mapowania identyfikatorów na niezmiennym ID dostawcy.
W pierwszej kolejności zaimplementuj odczyty; zaimportuj dane referencyjne przed jakimkolwiek zapisem.
Dodaj zadanie synchronizacji początkowej z paginacją, ograniczeniem liczby żądań, punktami kontrolnymi i kolejkowaniem zależności.
Zaimplementuj jeden wąski zapis (utworzenie faktury) dopiero po zweryfikowaniu mapowań klienta, pozycji, podatków i kont.
Spraw, aby zapisy były odporne na ponowne próby dzięki wewnętrznym identyfikatorom operacji, ograniczeniom unikalności i sprawdzeniom stanu zdalnego.
Dodaj podpisane webhooki, które szybko odpowiadają i przetwarzają dane asynchronicznie.
Dodaj odpytywanie i uzgadnianie danych, aby webhooki były przyspieszeniem, a nie jedynym źródłem prawdy.
Celowo przetestuj scenariusze awarii.
Dodaj narzędzia wsparcia i audytu, dzięki którym awarie będą zrozumiałe i naprawialne.
Stopniowo poszerzaj zakres obsługiwanych obiektów.

FAQ

Czy powinienem użyć ujednoliconego API, czy zbudować bezpośrednie konektory?

Użyj bezpośredniego konektora, gdy jeden dostawca dominuje wśród Twoich klientów lub gdy kluczowe jest zachowanie specyficzne dla danego dostawcy. Rozważ ujednolicone API, gdy szerszy zasięg i szybkość są ważniejsze niż kontrola. Jeśli Twoją prawdziwą potrzebą jest samodzielne prowadzenie ksiąg, a nie synchronizacja z systemem klienta, żadna z tych opcji nie jest odpowiedzią – spójrz wówczas na wbudowaną księgę główną, taką jak Nordlet.

Czy webhooki wystarczą, aby utrzymać synchronizację?

Nie. Webhooki bywają wyłączane, opóźniane lub gubione, a ładunki danych mogą być niekompletne lub uporządkowane w niewłaściwej kolejności. Traktuj je jako sygnały o zmianach, pobieraj aktualny obiekt po ich otrzymaniu i wspomagaj je okresowym odpytywaniem oraz procedurą uzgadniania danych.

Jak zapobiec sytuacji, w której błędy tokena odświeżania odcinają klientów?

Zapisuj najnowszy token odświeżania atomowo przy każdym odświeżeniu, używaj blokady dla każdego połączenia, ponawiaj próby przy chwilowych awariach endpointu tokenów i eksponuj czytelny stan ponownej autoryzacji. 30-minutowy okres karencji Xero pomaga, ale to atomowy zapis ratuje sytuację.

Czy mogę dopasowywać rekordy po nazwisku/nazwie klienta lub adresie e-mail?

Nie jako stałym identyfikatorem. Nazwy się zmieniają, zdarzają się duplikaty, a dwóch klientów może dzielić ten sam e-mail. Przechowuj niezmienne ID dostawcy i trzymaj obok niego własne ID z SaaS.