Integracja programu do faktur z księgowością i sklepem

Sklep, program do faktur i księgowość mogą wymieniać dane bez ręcznego przepisywania. Zanim uruchomisz integrację, ustal kierunek przepływu i sposób obsługi błędów.
Fakturownia udostępnia bezpłatne API (0 zł), które pozwala łączyć ją z systemami sprzedażowymi i aplikacjami biznesowymi oraz automatycznie wystawiać faktury.¹

Czym jest API do fakturowania i jak działa synchronizacja danych?

API do fakturowania pozwala programom wymieniać dane bez ręcznego przepisywania dokumentów. Zasady synchronizacji określają, jakie informacje trafiają między sklepem, programem do faktur i księgowością oraz gdzie znajduje się ich aktualna wersja. W API Fakturowni żądanie GET /invoices.json pobiera listę faktur, a POST /invoices.json tworzy nową fakturę².

Każdy rodzaj danych potrzebuje wskazanego systemu źródłowego. To w nim należy poprawiać rozbieżności, zamiast zmieniać ten sam zapis w kilku miejscach. Tabela pokazuje przykładowy podział odpowiedzialności³.

Jakie dane można wymieniać przez API: faktury, kontrahentów czy produkty?

Dane przekazywane przez API można podzielić na faktury, kontrahentów i produkty. Każda grupa wymaga innych pól oraz odrębnej kontroli zmian. Faktyczny zakres wymiany zależy od możliwości połączonych systemów⁴.

Tabela pokazuje, do czego służą poszczególne dane w połączeniu sklepu, programu do faktur i księgowości.

Dane w tabeli: 5

Faktura dokumentuje sprzedaż; dane kontrahenta i produktu pomagają ją przygotować. Ustal, czy księgowość potrzebuje tylko gotowego dokumentu, czy również danych użytych przy jego wystawieniu.
Art. 106e ust. 1 pkt 7 ustawy o VAT wymaga podania na fakturze nazwy lub rodzaju towaru albo usługi⁶.

Jak skonfigurować dostęp API i połączyć program do faktur z księgowością lub sklepem?

Konfigurację dostępu API zacznij od rozpisania przepływu: który system przekazuje dane, a który odbiera gotową fakturę. Po połączeniu systemu sprzedażowego z API Fakturowni zamówienie może posłużyć do wystawienia dokumentu dla księgowej. Sklep wysyła w tym celu żądanie POST /invoices.json z danymi zamówienia².

Przed uruchomieniem takiego połączenia zaplanuj poniższe czynności:

• Mapowanie pól przypisuje dane zamówienia do pól faktury. Obejmuje dane nabywcy, pozycje sprzedaży i płatność.
• Ustalenie dostępu określa, która aplikacja wysyła dane i odbiera odpowiedzi API. Ogranicz jej dostęp do operacji potrzebnych integracji.
• Kontrola odpowiedzi pozwala rozpoznać, czy dokument powstał, czy wystąpił błąd. Bez potwierdzenia system sprzedażowy nie powinien oznaczać faktury jako wystawionej.

Przepływ zaczyna się od zamówienia i prowadzi do faktury, ale dopiero odpowiedź API potwierdza wynik. Odpowiedź na żądanie wystawienia zawiera pole id. Dzięki niemu można później pobrać dokument⁷.

Jak ustalić kierunek i częstotliwość synchronizacji danych?

Ustal kierunek synchronizacji osobno dla zamówień, faktur i płatności. Zmiana powinna przechodzić z systemu źródłowego do tego, który jej potrzebuje; inaczej aplikacje mogą nadpisywać sobie dane. Żądanie PUT /invoices/{id}.json zmienia istniejącą fakturę, a POST /invoices.json tworzy nowy dokument².

Częstotliwość wymiany dopasuj do chwili, w której dane są potrzebne. Faktura może powstać po potwierdzeniu sprzedaży, a do księgowej trafić zgodnie z harmonogramem pracy. Określ też, czy ponowienie operacji po błędzie zmieni istniejący zapis, czy utworzy kolejny, oraz kiedy sprawdzisz wynik.
Zgodnie z art. 106i ust. 1 ustawy o VAT fakturę wystawia się zasadniczo do 15. dnia miesiąca po dostawie lub wykonaniu usługi⁶.

Jakie możliwości API mają znaczenie przy wyborze programu do faktur?

Wybierając program do faktur, przyjrzyj się operacjom API potrzebnym w Twoim procesie. Liczy się utworzenie dokumentu, odczyt jego statusu i przekazanie danych dalej. Sklep wystawiający faktury automatycznie musi też powiązać dokument z zamówieniem, na przykład zapisując przy nim pole id z odpowiedzi API⁷.

Księgowa potrzebuje danych do zaksięgowania sprzedaży. Właściciel sklepu chce natomiast wiedzieć, czy faktura rzeczywiście powstała. Oceniaj więc przepływ danych i obsługę odpowiedzi, a nie samą możliwość połączenia aplikacji⁴.

Czym są klucze API i do czego służą w integracji?

Klucze API uwierzytelniają aplikację korzystającą z funkcji programu do faktur. Integracja Easytools z Fakturownią wymaga tokenu API dostępnego w ustawieniach konta Fakturowni¹. Token identyfikuje dostęp aplikacji, ale nie wyznacza samodzielnie zakresu wymienianych danych. W Fakturowni znajdziesz go pod ścieżką: Ustawienia → Ustawienia konta → Integracja → Kod autoryzacyjny API⁴.

Jak klucze API chronią dostęp do danych i jakie wiążą się z nimi ryzyka?

Klucz API chroni dostęp do danych tylko wtedy, gdy pozostaje poufny. Trzymaj token poza publicznym kodem aplikacji i udostępniaj go wyłącznie osobom, które go potrzebują. Po ujawnieniu klucza odbierz mu dostęp i zastąp go nowym, ponieważ jego posiadacz może korzystać z uprawnień połączenia.
Do przesyłania tokenu stosuj TLS 1.3, dopuszczając TLS 1.2 jako najstarszą wersję ze względów zgodności⁸.

Jak przygotować klucze API przed uruchomieniem integracji?

Przypisz klucz API do konkretnego połączenia i wyznacz osobę odpowiedzialną za jego przechowywanie. Nadaj uprawnienia potrzebne do wymiany danych, a token przekaż wdrażającemu bez publikowania go w dokumentacji. Przed uruchomieniem przetestuj planowaną operację i reakcję aplikacji na odmowę dostępu.
Przy żądaniu bez prawidłowego uwierzytelnienia serwer powinien zwrócić kod HTTP 401, zgodnie z RFC 9110⁹.

Gdzie wykorzystuje się klucze API przy wymianie danych?

Połączona aplikacja dołącza klucz API do żądań wysyłanych do programu do faktur. Klucz uwierzytelnia operację na dokumencie lub danych klienta, a odpowiedź informuje o jej wyniku. Nie wpisuj klucza na fakturze ani nie przekazuj go odbiorcy dokumentu. W przykładach żądań API Fakturowni parametr z tokenem nosi nazwę api_token².

Jak klucze API wpływają na pracę zespołu wdrażającego integrację?

Zespół wdrażający powinien ustalić właściciela klucza API i sposób przekazywania dostępu. Programista konfiguruje uwierzytelnienie, a osoba odpowiedzialna za konto kontroluje nadawanie i odbieranie uprawnień. Gdy zmienia się opiekun integracji, zespół powinien przejrzeć aktywne klucze oraz uprawnienia połączenia.
Art. 32 ust. 1 lit. b RODO wymaga odpowiednich środków zapewniających ciągłą poufność systemów i usług przetwarzających dane osobowe¹⁰.

Dlaczego integracja przez API do fakturowania gubi lub dubluje dane?

Integracja może zgubić lub zdublować dane, jeśli nie sprawdza wyniku wysyłki albo bez kontroli ponawia tworzenie faktury. Według dokumentacji Fakturowni jej webhook, czyli powiadomienie po zmianie danych, nie zgłasza błędu wysyłki do KSeF. Taki błąd nie aktualizuje bowiem faktury¹¹.
Brak powiadomienia nie potwierdza powodzenia wysyłki. Przed ponowieniem operacji odczytaj pole gov_status przez GET /invoices/{id}.json; szczegóły błędu znajdziesz w gov_error_messages¹².

Skąd biorą się brakujące, błędne lub zdublowane faktury?

Faktura może nie powstać, choć integracja wysłała żądanie – samo wysłanie nie potwierdza utworzenia dokumentu. Nieprawidłowe przypisanie pól zamówienia do pól faktury prowadzi z kolei do błędnych danych. Po zerwaniu połączenia aplikacja może ponowić żądanie, mimo że poprzednie utworzyło już fakturę. Powiązanie identyfikatorów zamówienia i faktury pomaga wykryć taki przypadek przed ponowieniem operacji.

Jak sprawdzić działanie połączenia i poprawność synchronizacji?

Sprawdź połączenie, zestawiając zamówienie, fakturę i jej status wysyłki w systemie docelowym. Porównaj dane nabywcy i kwoty, identyfikator dokumentu zapisany przy zamówieniu oraz odpowiedź na żądanie. Przy przekazywaniu faktury do KSeF błędy trzeba wykrywać przez odpytywanie API Fakturowni o status, czyli polling, lub monitorowanie szczegółów faktur¹¹. Oznacz dokument jako przekazany dopiero po ustaleniu wyniku właściwej operacji.

Czym API różni się od gotowego połączenia, importu plików i ręcznego przekazywania danych?

Tabela zestawia sposoby przekazywania danych z czynnościami kontrolnymi, które pozostają po stronie firmy.

Każda metoda wymaga ustalenia, kto sprawdza wynik przekazania faktury. Ta sama osoba lub wyznaczony zespół musi też zająć się wykrytymi błędami.

Proste funkcje programu do faktur, które ułatwiają integrację

Program do faktur ułatwia połączenie, jeśli pozwala odczytać dokument, powiązać go z zamówieniem i ustalić jego status. Identyfikator pomaga odnaleźć fakturę po przekazaniu danych ze sklepu. Podgląd nabywcy i pozycji sprzedaży umożliwia porównanie dokumentu z zamówieniem, a status odróżnia zapis od zakończonej wysyłki.

Historia zmian dokumentu pomaga sprawdzić, czy rozbieżność istniała przed wystawieniem faktury, czy pojawiła się po edycji. Wyszukiwanie po identyfikatorze zamówienia ogranicza ręczne przeglądanie dokumentów. Przy wyborze programu oceń te możliwości zarówno w codziennej pracy, jak i w używanym przez firmę sposobie wymiany danych⁴.

Czy bezpłatna integracja z KSeF obejmuje potrzebną wymianę danych?

Integracja z KSeF i połączenie programu ze sklepem lub księgowością dotyczą różnych etapów obiegu faktury. Bezpłatne połączenie nie musi obejmować wszystkich tych etapów. Według dokumentacji Fakturowni wysyłka do KSeF obsługuje 3 tryby: online, offline i offline24, a aktualny tryb można odczytać z odpowiedzi API¹¹.

Tabela pokazuje kierunek i cel każdego połączenia oraz informację potrzebną po wysyłce:

Połączenie z KSeF służy wysyłce faktury do tego systemu. Nie zastępuje pobierania zamówień ze sklepu ani przekazywania dokumentów księgowości.

Szybkie fakturowanie po połączeniu programu ze sklepem

Integracja Easytools z Fakturownią przesyła dane transakcji przez API i pozwala wystawiać faktury bez udziału użytkownika¹. Automatyzacja usuwa z tego procesu ręczne przepisywanie danych sprzedaży.
Właściciel sklepu nadal musi wiedzieć, czy dokument powstał. Księgowa potrzebuje natomiast danych faktury do zaksięgowania sprzedaży.

Obsługa faktur po integracji: dokumenty cykliczne i międzynarodowe

Po uruchomieniu integracji trzeba powiązać faktury ze sprzedażą i kontrolować, czy można wykonać kolejną operację. Według dokumentacji Fakturowni produkcyjny KSeF może odrzucić fakturę końcową wystawianą przez API, zanim powiązane zaliczki otrzymają numery KSeF¹¹. Po nadaniu numeru zaliczce odpowiedź API zawiera wypełnione pole gov_id, a gov_status przyjmuje wartość ok¹¹.

Nadanie zaliczce numeru KSeF można wykryć przez webhook invoice:update lub odpytanie API Fakturowni¹¹. W produkcyjnym KSeF błąd API może wystąpić przy edycji lub usunięciu faktury po zleceniu wysyłki. Może też pojawić się przy pobraniu PDF przed nadaniem numeru KSeF¹¹. Wysyłka e-maila przez API Fakturowni może zwrócić ok, choć wiadomość wyjdzie dopiero po nadaniu numeru¹¹.
Odpowiedź na zlecenie nie oznacza więc natychmiastowego dostarczenia e-maila.

Jak synchronizować faktury cykliczne?

Faktury cykliczne synchronizuj tak, by każdy wygenerowany dokument odpowiadał właściwemu okresowi rozliczeniowemu i odbiorcy. Do księgowości przekaż wystawioną fakturę, nie samą regułę jej tworzenia. Gdy ponawiasz synchronizację, rozpoznaj dokument po identyfikatorze. To pozwoli uniknąć ponownego zaksięgowania.

Jak przekazywać dane faktur międzynarodowych?

Dane faktur międzynarodowych przekazuj razem z walutą, danymi zagranicznego nabywcy i oznaczeniami podatkowymi zapisanymi na dokumencie. Mapowanie pól nie powinno zastępować tych wartości domyślnymi ustawieniami sprzedaży krajowej. Księgowa może wtedy zaksięgować fakturę na podstawie danych właściwych dla danej transakcji.

Aplikacja mobilna a synchronizacja faktur między urządzeniami

Aplikacja mobilna ułatwia pracę na różnych urządzeniach, jeśli korzysta z tych samych danych konta co program na komputerze. Faktura wystawiona na telefonie powinna trafić do programu używanego przez księgową. Osobna kopia dokumentu utrudniłaby utrzymanie zgodności zapisów.

Synchronizacja między urządzeniami daje użytkownikom dostęp do dokumentów, a integracja przez API wymienia dane z innymi systemami. Właściciel firmy potrzebuje na telefonie aktualnej faktury, księgowa zaś tego samego zapisu do rozliczenia sprzedaży. Przy wyborze programu sprawdź, czy oba urządzenia pokazują ten sam dokument wraz z jego zmianami.

Integracje Fakturowni: zakres wymiany danych przez API do fakturowania

Integracje Fakturowni oceniaj przez pryzmat przepływu potrzebnego między sklepem, programem do faktur i księgowością. Według Fakturowni wszystkie funkcje można bezpłatnie testować przez 30 dni¹³. W tym czasie warto przejść drogę od utworzenia faktury przez odczyt wyniku po przekazanie dokumentu do dalszej obsługi¹⁴.

Jak ocenić przydatność integracji Fakturowni do własnego procesu?

Przyjrzyj się integracji Fakturowni na tle własnej ścieżki sprzedaży: od zamówienia po dokument potrzebny księgowej. Rozpisz czynności wykonywane przez połączenie i te, które zostaną po stronie pracownika. Przydatność zależy od tego podziału pracy i dostępnych operacji, nie od samej możliwości połączenia aplikacji.

Jakie funkcje Fakturowni mają znaczenie przy wymianie danych?

Przy wymianie danych liczy się możliwość utworzenia faktury, odczytania jej treści i ustalenia wyniku wysyłki. Środowisko demonstracyjne Fakturowni nie odtwarza wszystkich zabezpieczeń produkcyjnego KSeF ani nie generuje kodów QR¹¹. Powodzenie operacji w środowisku demonstracyjnym nie potwierdza więc działania tych elementów w produkcyjnym obiegu.

Jak sprawdzić możliwości integracji Fakturowni z księgowością lub sklepem?

Przeprowadź próbny przepływ odpowiadający pracy firmy. Przekaż dane sprzedaży, odczytaj fakturę i porównaj ją z informacjami potrzebnymi księgowości. Zapisz oddzielnie wynik utworzenia dokumentu i wynik jego dalszego przekazania. Zobaczysz wtedy, które etapy obsługuje połączenie, a które wymagają osobnej czynności.

Co zrobić z fakturą wystawioną w trybie offline?

Fakturę wystawioną w trybie offline można po ustąpieniu awarii skierować do KSeF przez API Fakturowni¹¹. Fakturownia stosuje ten tryb, gdy serwis latarni KSeF zgłasza niedostępność systemu¹¹. Sam błąd server_error przy wysyłce z Fakturowni nie oznacza awarii KSeF i nie uruchamia trybu offline¹¹.

Tryb offline24 w Fakturowni może wynikać z wydłużonego przetwarzania faktur w KSeF lub odpowiednio skonfigurowanej wysyłki masowej¹¹. W przypadku opisanym przez Fakturownię faktura ma przed wysyłką 2 kody QR¹¹.
Zanim ponowisz operację, odróżnij tryb dokumentu od błędu odpowiedzi API. Wtedy skierujesz do wysyłki właściwą fakturę.

Przydatna dokumentacja integracji i KSeF

Dokumentacja integracji wyjaśnia format żądań API, znaczenie odpowiedzi i sposób rozpoznawania błędów. Na jej podstawie zespół może ustalić zakres danych przesyłanych przez sklep. Może też określić, jak zapisać wynik operacji przy właściwym zamówieniu.

Dokumentacja KSeF opisuje zasady przekazywania faktur ustrukturyzowanych oraz znaczenie ich statusów. W opisie połączenia oddziel zapis faktury w programie od jej przyjęcia przez KSeF. Dzięki temu wiadomo, na którym etapie trzeba obsłużyć błąd.

Ceny i warunki sprawdzone u źródeł: październik 2026.

Stan prawny na: październik 2026.