Fakturownia API jedna faktura na jedno zamówienie
Ta strona jest o warstwie technicznej: token i adres konta, pola, bez których dokument nie powstanie, idempotencja, numeracja po stronie Fakturowni, korekta jako osobny dokument, pobranie pliku i wysyłka do KSeF. Powody biznesowe opisujemy osobno. Tutaj piszemy, jak spiąć to tak, żeby ponowione zapytanie nie wystawiło drugiej faktury.
- 1 zamówienie, 1 fakturaidentyfikator zamówienia zapisany na dokumencie i sprawdzany przed zapisem, żeby ponowienie po timeoucie nie wystawiło duplikatu
- 1 kwietnia 2026od tego dnia faktury w KSeF wystawiają pozostali podatnicy VAT, najwięksi od 1 lutego 2026. Ministerstwo Finansów
- 2 do 4 tygodniod warsztatu do integracji na produkcji, sprawdzonej na Waszych dokumentach z ostatniego miesiąca
Problem
Dlaczego integracja wystawia dwie faktury za to samo zamówienie?
Zapytanie o wystawienie dokumentu wychodzi, po drodze pada timeout, odpowiedź nie wraca. Scenariusz ponawia próbę, bo tak go ustawiono, i po drugiej stronie powstaje druga faktura z kolejnym numerem z tej samej serii. Do naprawy trzeba korekty albo anulowania, a w numeracji zostaje ślad. Nie wynika to z awarii Fakturowni, tylko z braku jednego warunku przed zapisem.
Drugi błąd jest cichszy. Pozycja bez stawki VAT, NIP z jedną cyfrą za dużo, brak kodu kraju przy sprzedaży zagranicznej: dokument nie powstaje, interfejs zwraca listę pól, które nie przeszły walidacji, a scenariusz kończy się czerwonym wykonaniem, którego nikt nie widzi. Sprzedaż jest zamknięta, faktury nie ma, wychodzi to na przeglądzie miesiąca.
Trzecia rzecz to termin, którego nie da się przesunąć. Obowiązek wystawiania faktur w Krajowym Systemie e-Faktur ruszył 1 lutego 2026 dla największych podatników i 1 kwietnia 2026 dla pozostałych, a okres przejściowy bez sankcji trwa do końca 2026 roku. Terminy i strukturę dokumentu publikuje Ministerstwo Finansów na podatki.gov.pl. Dla integracji znaczy to jedno: braki w danych kontrahenta, które wcześniej przechodziły, zatrzymują teraz dokument na wysyłce, a odrzucenie jest osobnym zdarzeniem i musi mieć adresata.
- Ponowienie po timeoucie wystawia drugi dokument z kolejnym numerem serii
- Czerwone wykonanie scenariusza nikogo nie budzi, więc faktury brakuje tydzień
- Numer i plik zostają w panelu, a handlowiec dopytuje o nie mailem
- Token wklejony wprost do scenariusza wędruje razem z jego kopią na testy
- Odrzucenie z KSeF czeka w panelu, dopóki ktoś tam nie zajrzy
- Masowy import bez kolejki wpada w limit zapytań i kończy się w połowie
Dlaczego teraz
Co robi Fakturownia, a co musi zrobić integracja?
Po stronie Fakturowni jest więcej, niż zwykle wykorzystuje pierwsza wersja integracji. Numer nadaje ona sama z serii wskazanej w zapytaniu, wiąże korektę z dokumentem pierwotnym, trzyma szablony i faktury cykliczne, udostępnia plik dokumentu do pobrania, wysyła go mailem do kontrahenta i obsługuje wysyłkę do KSeF razem ze zwrotnym numerem oraz statusem. Uwierzytelnienie idzie tokenem z panelu, a adresem jest subdomena Waszego konta, więc jeden token nie otwiera cudzych danych.
Reszta jest po naszej stronie i tam siedzi ryzyko: wyzwalacz, mapowanie pól, klucz zewnętrzny dla idempotencji, ponowienia z rosnącym odstępem, kolejka na błędy walidacji, monitoring. Limit zapytań na minutę i dokładny sposób przekazania tokenu bierzemy z dokumentacji Fakturowni, a nie z pamięci: sprawdzamy je przed wdrożeniem i pod nie projektujemy kolejkę.
Ta strona jest o technice. Po co spinać sprzedaż z fakturowaniem i co z tego ma firma, opisujemy na stronie integracji z Fakturownią, a sposób pracy z dowolnym interfejsem na stronie integracji przez API. Tutaj mówimy o pojedynczych operacjach: co wysyłamy, co wraca i co się dzieje, gdy nie wróci.
Do tego dochodzi agent AI. BOND, nasz firmowy agent AI, czyta dane przez ten sam interfejs i odpowiada zdaniem w 5 do 10 sekund, na przykład na pytanie, które dokumenty z tego kwartału mają korektę. Dla integracji ważne jest to, że agent liczy się do tego samego limitu zapytań, dlatego dane do odczytu bierzemy z hurtowni, a nie za każdym razem wprost z Fakturowni.
Co się zmienia
Co dostaje osoba, która to utrzymuje?
Jedna faktura na jedno zamówienie
Identyfikator zamówienia zapisujemy na dokumencie i sprawdzamy przed wystawieniem, a samą operację blokujemy na czas zapisu. Ponowienie po timeoucie trafia na istniejący dokument i zwraca jego numer, zamiast tworzyć drugi.
Jeden warunek przed zapisem zamiast korekty i tłumaczenia luki w numeracji
Numer i seria zostają po stronie Fakturowni
Numer nadaje Fakturownia z serii wskazanej w zapytaniu, więc integracja nie liczy numerów u siebie i nie ma czego rozjechać. Dokument z datą wsteczną albo poza serią zatrzymujemy i przekazujemy księgowości.
Zero numerów generowanych po naszej stronie, zero luk do wyjaśniania
Błąd walidacji ma adresata
Zły NIP, pozycja bez stawki VAT albo brak kodu kraju wracają jako lista pól, które nie przeszły. Zgłoszenie idzie do kolejki z treścią błędu, numerem zamówienia i linkiem do rekordu, a nie do logu, do którego nikt nie zagląda.
NIP sprawdzamy w rejestrze przed wystawieniem, nie po korekcie
Korekta jako osobny dokument
Wystawionej faktury nie edytujemy. Korekta powstaje jako nowy dokument powiązany z pierwotnym, więc saldo kontrahenta jest aktualne tego samego dnia, a korekta zmieniająca kwotę domyślnie czeka na człowieka.
Powiązanie z fakturą pierwotną zapisane w dokumencie, nie w komentarzu
Plik i wysyłka bez wchodzenia do panelu
Po wystawieniu pobieramy plik dokumentu i zapisujemy jego adres na rekordzie w CRM oraz w archiwum na dysku. Wiadomość do kontrahenta wychodzi z Fakturowni albo z Waszego systemu, zależnie od tego, z jakiego adresu ma wyjść.
Numer i plik widoczne na rekordzie w kilka sekund po wystawieniu
KSeF obsłużony razem z odrzuceniem
Wysyłkę do Krajowego Systemu e-Faktur robi Fakturownia, a integracja dopisuje zwrotny numer i status do CRM oraz do archiwum. Odrzucony dokument nie zostaje w panelu bez opieki: workflow zgłasza go księgowości z treścią błędu.
Obowiązek objął pozostałych podatników VAT 1 kwietnia 2026, największych 1 lutego 2026
A u Ciebie
Co, jeśli piszemy tę integrację sami?
Cztery zdania, które słyszymy najczęściej od osób technicznych, i to, co na nie odpowiadamy. Jeśli Twoje brzmi inaczej, powiedz je na konsultacji: to najszybszy sposób sprawdzenia, czy jest tu w ogóle o czym rozmawiać.
Mamy już skrypt, który wystawia faktury, działa od roku.
Wtedy nie przepisujemy go od zera. Sprawdzamy trzy rzeczy: czy ponowienie po timeoucie może wystawić drugi dokument, gdzie leży token i kto widzi błąd walidacji. Jeśli te trzy odpowiedzi są dobre, mówimy to i kończymy na warsztacie. Najczęściej brakuje jednej: skrypty pisane pod pierwszy scenariusz zwykle nie mają klucza zewnętrznego.
Nie damy zewnętrznej firmie tokenu do naszego konta.
I nie musisz. Token wystawiasz po swojej stronie, z zakresem ustalonym na warsztacie, i unieważniasz go w panelu jednym kliknięciem. Na czas budowy pracujemy na oddzielnym koncie testowym z własnym tokenem, a token produkcyjny wkładasz do sejfu sekretów sam, bez przesyłania go nam mailem.
Po co idempotencja, u nas jeszcze nie było duplikatu.
Duplikat nie przychodzi z ruchem, przychodzi z jednym timeoutem w złym momencie. Koszt to korekta, tłumaczenie luki w numeracji i telefon od kontrahenta, który dostał dwa dokumenty za jedno zamówienie. Zabezpieczenie to jeden warunek przed zapisem plus rejestr par: identyfikator zamówienia i identyfikator dokumentu.
Nie mamy sandboksa, boimy się testów na produkcji.
Dlatego pilot idzie na oddzielnym koncie z własnym tokenem i własną serią numeracji, a nie na Waszym koncie produkcyjnym. Czy Fakturownia daje środowisko testowe do API, sprawdzamy w dokumentacji przed wdrożeniem, zamiast zakładać. Testujemy na dokumentach z ostatniego miesiąca, więc dane wejściowe są prawdziwe, a numeracja nie.
- System fakturowy i ERP
- Fakturownia, iFirma, Subiekt, Comarch Optima, sevDesk
- CRM i szanse sprzedaży
- HubSpot, Pipedrive, Salesforce, LiveSpace
- Sprzedaż i zamówienia
- BaseLinker, Allegro, Shopify, WooCommerce, PrestaShop
- KSeF, archiwum i powiadomienia
- Krajowy System e-Faktur, Google Workspace, Microsoft 365, Slack, Notion
- Dane i raporty
- BigQuery, Google Sheets, bazy SQL, GA4
- Warstwa automatyzacji
- n8n, Make, Zapier, własne integracje przez API
Operacje w Fakturowni: jak je realizujemy i o czym pamiętamy
Siedem operacji, z których składa się większość integracji fakturowych. Trzecia kolumna to miejsca, w których te integracje najczęściej się psują, spisane po to, żeby projekt nie zaczynał się od nauki na własnym duplikacie.
| Operacja | Sposób realizacji | O czym pamiętać |
|---|---|---|
| Uwierzytelnienie | token z panelu Fakturowni plus adres konta, czyli Wasza subdomena | token nie wygasa sam, unieważniasz go w panelu; trzymamy go w sejfie sekretów, nie w treści scenariusza |
| Wystawienie dokumentu | jedno zapytanie z rodzajem dokumentu, datami, kontrahentem i pozycjami | pozycja bez stawki VAT albo bez ceny nie przejdzie walidacji, dokument wtedy nie powstaje |
| Kontrahent | dopasowanie po NIP przed wystawieniem, dopiero potem założenie nowego | kluczem jest NIP, nie nazwa firmy; dwa rekordy na jeden NIP rozjeżdżają saldo |
| Numer i seria | nadaje Fakturownia z serii wskazanej w zapytaniu | numer liczony po stronie integracji daje luki i duplikaty w serii |
| Idempotencja | identyfikator zamówienia zapisany na dokumencie, sprawdzany przed zapisem | bez tego sprawdzenia samo ponowienie po timeoucie wystawia drugą fakturę |
| Korekta | nowy dokument powiązany z fakturą pierwotną | wystawionej faktury się nie edytuje; korekta zmieniająca kwotę czeka na człowieka |
| Plik i wysyłka do KSeF | pobranie pliku dokumentu, wysyłkę do KSeF robi Fakturownia | zwrotny numer i status dopisujemy do CRM, a odrzucenie zgłaszamy księgowości |
Limit zapytań na minutę i dokładny sposób przekazania tokenu bierzemy z dokumentacji Fakturowni i sprawdzamy przed wdrożeniem, zamiast wpisywać liczbę z cudzego wpisu na forum. Pod ten limit projektujemy kolejkę z odstępem i ponowienia z rosnącą przerwą, a masowy import puszczamy w paczkach poza godzinami pracy.
Jak to robimy
Pięć kroków od pierwszego zapytania do integracji na produkcji
Każdy krok kończy się czymś, co możesz ocenić, zanim zdecydujesz o następnym. Najpierw proces, potem narzędzia, nigdy odwrotnie.
Warsztat i przegląd interfejsu
Spisujemy, co ma wyzwalać dokument, jakie pola wchodzą do zapytania i skąd się biorą, oraz które przypadki nie mają jednoznacznej reguły: sprzedaż bez NIP, zwrot po dwóch miesiącach, dokument walutowy. Po stronie technicznej sprawdzamy zakres tokenu, limit zapytań i to, czy operacje, których potrzebujemy, są w dokumentacji.
Mapowanie pól i projekt idempotencji
Ustalamy mapowanie rekordu na dokument, wybór serii, klucz zewnętrzny i miejsce rejestru par: identyfikator zamówienia i identyfikator dokumentu. Do tego polityka ponowień, obsługa błędów walidacji i lista dokumentów, których automat nie wystawia sam. Ta lista powstaje przed wyborem narzędzia, nie po nim.
Pilot na koncie testowym
Workflow działa obok obecnego trybu pracy, na dokumentach z ostatniego miesiąca i na oddzielnym koncie z własną serią. Sprawdzamy przypadki trudne, nie łatwe: ponowienie po timeoucie, zły NIP, pozycję bez stawki, korektę, dokument walutowy i odrzucenie z KSeF.
Produkcja, monitoring i przekazanie
Przełączamy na produkcję z alertem na błąd walidacji i na odrzucenie z KSeF. Token produkcyjny wkładasz do sejfu sekretów sam. Zostaje u Was workflow, rejestr par, opis pól i instrukcja, co robić przy odrzuceniu, więc kolejną serię albo nowy szablon dopisujecie bez nas.
Pomiar po 30 i 90 dniach
Patrzymy na cztery liczby: ile dokumentów powstało bez człowieka, ile trafiło do kolejki na weryfikację, ile zapytań wymagało ponowienia i ile duplikatów wyszło z ponowień. Ostatnia z nich ma być zerem. Dopiero na tej podstawie rozmawiamy o kolejnym zakresie.
Przed i po
Jak zmienia się tydzień osoby, która pilnuje integracji
Przedtem
- Rano przegląda historię wykonań scenariusza i szuka czerwonych
- Po zgłoszeniu od księgowej odkopuje, dlaczego dokument nie powstał
- Duplikat z ponowienia naprawia korektą i tłumaczy lukę w numerze
- Token do Fakturowni ma w treści scenariusza i w kopii na testy
Po zmianie
- Błąd walidacji przychodzi jako zgłoszenie z treścią i numerem zamówienia
- Dokument, którego automat nie tknie, stoi w kolejce z podanym powodem
- Ponowienie trafia na istniejący dokument i zwraca jego numer
- Token siedzi w sejfie sekretów, a konto testowe ma własny
Pierwsze dokumenty wystawione bez człowieka widać w dniu przełączenia. Liczbę zgłoszeń w kolejce i liczbę ponowień oceniamy po 30 dniach, a stabilność integracji po 90.
Dla osoby, która to zamawia
Co z tego ma osoba odpowiedzialna za systemy
Dostajesz integrację, która ma opis, a nie tylko autora. Mapowanie pól, wybór serii, klucz zewnętrzny i polityka ponowień są spisane, więc kolejna osoba nie musi odtwarzać reguł z podglądu scenariusza. Każdy dokument wystawiony bez człowieka ma ślad: co go wyzwoliło, z jakiego rekordu wzięły się dane i o której powstał.
Druga rzecz jest o ryzyku Twojego podpisu. Token wystawiasz i unieważniasz sam, testy idą na oddzielnym koncie, a pilot działa obok obecnego trybu pracy, więc stary sposób jest sprawny do końca sprawdzania. Zakres jest wąski, jedna integracja, więc pierwsza decyzja jest mała i odwracalna.
- Mapowanie pól i polityka ponowień spisane, nie ukryte w scenariuszu
- Token wystawiony u Was, w sejfie sekretów, odwoływalny jednym kliknięciem
- Pilot na oddzielnym koncie i własnej serii, produkcja nietknięta
- Alert na błąd walidacji i na odrzucenie z KSeF od pierwszego dnia
Ile to kosztuje
Warsztat ma cenę jawną, wdrożenie wycenę po nim
Warsztat procesowy kosztuje 2500 zł netto za tydzień i trwa od 1 do 7 tygodni. Przy jednej integracji zwykle wystarcza jeden tydzień, bo zakres jest wąski, ale ma wyjątki do spisania: serie, korekty, dokumenty walutowe, styk z biurem rachunkowym. Samą integrację wyceniamy po warsztacie, gdy wiadomo, ile wyzwalaczy wchodzi w zakres i w jakim stanie są dane kontrahentów. Więcej o warsztacie jest na stronie warsztatu procesowego.
Licencję Fakturowni i koszt działania workflow płacisz bezpośrednio dostawcy, na przykład n8n albo Make, albo nie płacisz wcale, gdy workflow stoi na Waszej infrastrukturze. Tak samo z kosztem użycia modeli przy agencie AI. Bez naszej prowizji i bez odsprzedaży licencji.
Warsztat procesowy
2500 zł netto
za tydzień, przy jednej integracji zwykle jeden tydzień
Zamknięta całość. Kończy się dokumentem technicznym, który możesz zrealizować własnymi rękami albo oddać innej firmie.
- Lista operacji i mapowanie pól z rekordu na dokument
- Projekt idempotencji: klucz zewnętrzny, sprawdzenie przed zapisem, rejestr par
- Polityka ponowień, obsługa błędów walidacji i limitu zapytań
- Lista dokumentów, które zostają przy człowieku, i powód dla każdego
- Najczęściej wybierany
Warsztat i integracja
Wycena po warsztacie
zakres wynika z liczby wyzwalaczy i stanu danych w CRM
Najczęściej wybierany wariant. Działająca integracja w 2 do 4 tygodni od warsztatu, sprawdzona na Waszych dokumentach.
- Wszystko z warsztatu
- Workflow w n8n, Make albo własny kod, spięty z Fakturownią i CRM
- Idempotencja, kolejka błędów walidacji i ponowienia z rosnącym odstępem
- Pobranie pliku, wysyłka do kontrahenta i obsługa odrzuceń z KSeF
- Pilot na koncie testowym, przełączenie z monitoringiem, przekazanie opisu
Integracja i agent AI
Wycena po warsztacie
dla firm, które pytają o faktury i należności kilka razy dziennie
Wszystko z integracji plus BOND, firmowy agent AI, który odpowiada na pytania o dokumenty zwykłym zdaniem.
- Wszystko z integracji Fakturowni
- Zasilanie hurtowni raz na dobę, żeby odczyty nie zjadały limitu zapytań
- Odpowiedź w 5 do 10 sekund: kto zalega, co skorygowane, co odrzucone
- Wdrożenie agenta zajmuje około 2 miesięcy, niezależnie od integracji
Warsztat kończy się dokumentem, który obroni się bez nas: listą operacji, mapowaniem pól i projektem idempotencji. Jeśli okaże się, że wystarczy dopisać jeden warunek do scenariusza, który już macie, mówimy to i pokazujemy gdzie, zamiast sprzedawać wdrożenie od zera.
Najczęstsze pytania
Skąd wziąć token do API Fakturowni?
Token wystawiasz w panelu Fakturowni, w ustawieniach konta, i jest przypisany do tego konta razem z jego adresem, czyli Waszą subdomeną. Nie wygasa sam, unieważniasz go w panelu, dlatego traktujemy go jak hasło: trzyma go sejf sekretów, a nie treść scenariusza. Dokładny sposób przekazania tokenu w zapytaniu bierzemy z dokumentacji Fakturowni i potwierdzamy przed wdrożeniem.
Jak nie wystawić dwóch faktur za to samo zamówienie?
Potrzebne są trzy rzeczy. Identyfikator zamówienia zapisany na dokumencie, sprawdzenie przed zapisem, czy dokument z tym identyfikatorem już istnieje, i rejestr par po Waszej stronie, wiążący zamówienie z wystawionym dokumentem. Wtedy ponowienie po timeoucie trafia na istniejący dokument i zwraca jego numer, zamiast tworzyć drugi.
Kto nadaje numer i serię dokumentu?
Fakturownia, z serii wskazanej w zapytaniu. Numerów nie liczymy po stronie integracji, bo równoległe zapytania i ponowienia robią wtedy luki oraz duplikaty w serii, a tłumaczenie ich księgowości kosztuje więcej niż całe wdrożenie. Integracja decyduje tylko o tym, do której serii dokument należy: krajowa sprzedaż, proforma, korekta, kanał zagraniczny.
Czy przez interfejs da się wystawić fakturę korygującą?
Tak. Korekta jest osobnym dokumentem powiązanym z fakturą pierwotną, a wystawionej faktury się nie edytuje. Korektę techniczną, wynikającą z przyjętego zwrotu, automat tworzy sam, żeby saldo kontrahenta było aktualne tego samego dnia. Korekta zmieniająca kwotę na innej podstawie domyślnie czeka na zatwierdzenie osoby od faktur, a notę korygującą wystawia nabywca.
Co KSeF zmienia w integracji z Fakturownią?
Wysyłkę do Krajowego Systemu e-Faktur robi Fakturownia, a integracja przyjmuje zwrotny numer i status oraz dopisuje je do CRM i do archiwum. Zmiana dla integracji jest w danych: braki, które wcześniej przechodziły, zatrzymują dokument na wysyłce, więc kontrahenta weryfikujemy przed wystawieniem. Terminy obowiązku, 1 lutego 2026 dla największych podatników i 1 kwietnia 2026 dla pozostałych, publikuje Ministerstwo Finansów na podatki.gov.pl.
Ile zapytań na minutę wolno wysłać?
Wartość limitu bierzemy z dokumentacji Fakturowni i sprawdzamy przed wdrożeniem, zamiast powtarzać liczbę z cudzego wpisu na forum. Niezależnie od niej integracja ma kolejkę z odstępem między zapytaniami i ponowienia z rosnącą przerwą, a masowy import idzie w paczkach poza godzinami pracy. Odczyty do raportów i do agenta AI kierujemy do hurtowni, żeby nie zjadały tego samego limitu.
Co się dzieje, gdy NIP jest zły albo brakuje stawki VAT?
Dokument nie powstaje, a interfejs zwraca listę pól, które nie przeszły walidacji. Ten błąd zamieniamy na zgłoszenie z treścią, numerem zamówienia i linkiem do rekordu, kierowane do osoby od faktur, a nie do logu. NIP sprawdzamy w rejestrze przed wystawieniem, bo poprawa danych przed dokumentem jest tańsza niż korekta po nim.
Czy Fakturownia ma środowisko testowe do API?
Zakładamy ostrożnie: obecność sandboksa sprawdzamy w dokumentacji przed wdrożeniem, a domyślnie pracujemy na oddzielnym koncie testowym z własnym tokenem i własną serią numeracji. Pilot dostaje prawdziwe dane wejściowe, czyli dokumenty z ostatniego miesiąca, i nieprawdziwą numerację. Produkcji nie dotykamy do momentu, w którym przypadki trudne przechodzą.
Sprawdźmy, czy Wasza integracja wystawi duplikat
Bezpłatna konsultacja trwa 30 minut. Opowiadasz, co dziś wyzwala fakturę, w czym jest zbudowany scenariusz i gdzie leży token. Wychodzisz z odpowiedzią na trzy pytania: czy ponowienie po timeoucie może wystawić drugi dokument, kto widzi błąd walidacji i co się stanie przy odrzuceniu z KSeF. Nie musisz na tym etapie udostępniać żadnego systemu.
Prowadzimy najwyżej dwa wdrożenia równocześnie, żeby przy każdym ktoś realnie siedział.
Umów bezpłatną konsultacjęPS. Jeśli Wasz scenariusz ponawia zapytanie po timeoucie i nie sprawdza wcześniej, czy dokument już istnieje, to jest dokładnie ten problem. Duplikat kosztuje korektę, lukę w numeracji i telefon od kontrahenta, a zabezpieczenie to jeden warunek przed zapisem. Po wdrożeniu na jedno zamówienie powstaje jedna faktura, a błąd walidacji ma adresata tego samego dnia. Piszesz bezpośrednio do Pawła.