iFirma API: integracja i automatyzacja bez faktury wystawionej dwa razy
Warstwa techniczna spięcia z iFirmą: osobne klucze API dla poszczególnych rodzajów operacji, podpis liczony z treści żądania, pola obowiązkowe dokumentu, numeracja nadawana po stronie iFirmy, korekty, KSeF i pobranie PDF. Do tego kontrola duplikatu, żeby jedno zamówienie nie skończyło się dwiema fakturami. Strona jest dla osoby, która musi wiedzieć, na czym to stanie, zanim zaakceptuje zakres.
- 3 rodzaje kluczyiFirma wydaje klucz osobno dla faktur, dla rachunków i dla operacji na abonencie. Klucz do faktur nie podpisze żądania z innej grupy, więc zakres ustalamy przed pierwszym wywołaniem
- 1 kwietnia 2026od tego dnia KSeF obejmuje pozostałych podatników, po 1 lutego 2026 dla największych. Harmonogram i odstępstwa czytamy na podatki.gov.pl przed każdym wdrożeniem
- 5 do 10 sekundtyle mija od zamknięcia zamówienia do wystawionego dokumentu, gdy proces idzie automatem, zamiast czekać na wolne pół godziny księgowej
- 14 dniod warsztatu do pierwszej integracji działającej na Waszym koncie, sprawdzonej wcześniej na koncie testowym z osobnymi kluczami
Problem
Dlaczego integracja z iFirmą wystawia fakturę dwa razy?
Scenariusz wywołuje iFirmę, połączenie się urywa, odpowiedź nie wraca. Automat robi to, co ma w naturze: ponawia. Faktura jest już wystawiona, więc w systemie leżą dwa dokumenty na to samo zamówienie, oba z własnym numerem, oba w rejestrze VAT. Odkrywa to księgowa przy zamknięciu miesiąca, a nie osoba, która ustawiała scenariusz.
Druga grupa problemów siedzi w kluczach. iFirma nie daje jednego tokenu na wszystko: klucz jest osobny dla faktur, osobny dla rachunków i osobny dla operacji na abonencie, a każde żądanie trzeba podpisać. Wgranie klucza do faktur w miejsce, które pyta o inne dane, kończy się odrzuceniem na poziomie podpisu, czyli komunikatem, który wygląda jak awaria uprawnień, a jest pomyłką w konfiguracji. Szczegóły podpisu i nazwy kluczy bierzemy z dokumentacji API iFirmy, a nie z pamięci.
Trzecia grupa to obowiązek. Faktura ustrukturyzowana w Krajowym Systemie e-Faktur obowiązuje od 1 lutego 2026 największych podatników i od 1 kwietnia 2026 pozostałych, z odstępstwem dla najmniejszych wystawców według harmonogramu na podatki.gov.pl. Dla integracji przesuwa się punkt końcowy procesu: „utworzyliśmy dokument w iFirmie” to już nie koniec, dopóki nie wiadomo, że dokument pojechał do KSeF i z jakim numerem.
- Dwie faktury na jedno zamówienie i korekta, którą ktoś musi wystawić ręcznie
- Numer faktury z arkusza rozjeżdża się z numeracją nadaną przez iFirmę
- Żądanie odbite z powodu literówki w NIP wraca do nikogo, bo nikt nie czyta logu
- Klucz API wpisany na sztywno w scenariuszu i nikt nie wie, kto go wygenerował
- Wysyłka dokumentu do KSeF zależy od tego, czy ktoś pamiętał, bo potwierdzenia nikt nie zapisuje
Dlaczego teraz
Co się zmieniło, że warto spiąć to teraz?
Faktura przestała być plikiem, który się wysyła. Po wejściu KSeF jest dokumentem przekazywanym między systemami, z własnym numerem i potwierdzeniem. Proces, który do tej pory kończył się PDF-em w mailu, musi mieć teraz zapisany stan wysyłki i miejsce, w którym widać odrzucenia. To praca dla integracji, nie dla człowieka przepisującego dane z panelu.
Po stronie iFirmy dostajesz REST i JSON, więc wystawienie dokumentu, kartotekę kontrahenta, pobranie danych firmy po NIP i plik PDF obsługujesz bez logowania do panelu. Zapłacona cena za ten komfort to uwierzytelnianie: klucz właściwy dla rodzaju operacji plus podpis liczony z żądania. Robi się to raz i schowane w warstwie integracji, przestaje przeszkadzać.
Nie namawiamy na zmianę systemu księgowego. iFirma siedzi w tysiącach jednoosobowych działalności i małych spółek, a księgowe znają ją na pamięć, więc wymiana narzędzia tylko dla wygody integratora jest najdroższą możliwą opcją. Zostawiamy iFirmę tam, gdzie jest, i dokładamy warstwę, która ją wywołuje.
Trzecia zmiana to agent AI. Integracja wystawi dokument, ale nie odpowie właścicielowi na pytanie „ile faktur z sierpnia nie ma jeszcze wpłaty”. BOND, nasz firmowy agent AI, odpowiada na to z danych firmy w 5 do 10 sekund, bez logowania do iFirmy i bez budowania raportu.
Co się zmienia
Co dostajesz po spięciu iFirmy?
Jedna faktura na jedno zamówienie
Każde wystawienie ma klucz wzięty z zamówienia. Przed wywołaniem sprawdzamy, czy dokument dla tego klucza już istnieje, a po wystawieniu zapisujemy numer z iFirmy przy zamówieniu. Ponowienie po zerwanym połączeniu trafia na zapis, nie na nowy dokument.
Klucz zamówienia sprawdzany przed wywołaniem, numer dokumentu zapisany po odpowiedzi
Klucze rozdzielone po rodzaju operacji
Klucz do faktur wystawia faktury i nic więcej. Rachunki i operacje na abonencie dostają własne klucze o własnym zakresie, każdy trzymany w sejfie narzędzia, a nie w treści scenariusza.
Zakres każdego klucza spisany na warsztacie, wymiana klucza bez przepisywania scenariusza
Numer dokumentu z iFirmy, nie z arkusza
Numer nadaje iFirma według schematu ustawionego w panelu. Integracja nie próbuje go zgadywać: bierze numer i identyfikator z odpowiedzi i wpisuje przy zamówieniu w CRM albo w systemie sprzedaży.
Numer i identyfikator dokumentu wracają do zamówienia, więc obie strony mówią o tym samym papierze
Błąd walidacji widać w minutach
NIP z literówką, pozycja bez stawki VAT, kwota w euro bez kursu. Takie żądanie iFirma odrzuca, a my łapiemy kod i komunikat, odkładamy dane wejściowe do kolejki i zakładamy zadanie osobie, która to poprawi.
Odrzucone żądanie ląduje w kolejce razem z danymi wejściowymi i treścią komunikatu
Korekta tą samą drogą co faktura
Wystawionej faktury nie edytujemy, bo nie na tym polega korekta. Dokument korygujący wskazuje fakturę pierwotną, ma własny numer i ten numer też wraca do zamówienia, żeby rozliczenie dało się odtworzyć.
Korekta wskazuje dokument pierwotny, oba numery widać przy tym samym zamówieniu
PDF tam, gdzie jest potrzebny
Plik pobieramy po identyfikatorze dokumentu i podpinamy tam, gdzie go ktoś szuka: przy zamówieniu, w karcie klienta, na dysku firmowym. Wysyłkę do klienta robi iFirma albo Wasza skrzynka, zależnie od tego, kto ma być nadawcą.
PDF przy zamówieniu i w karcie klienta, bez pobierania z panelu ręcznie
A u Ciebie
Co, jeśli mamy już scenariusz w Make?
Cztery zdania, które słyszymy najczęściej przy iFirmie, i to, co na nie odpowiadamy.
Odpowiedź na każde z nich zaczyna się od sprawdzenia stanu, nie od obietnicy. Dlatego pierwszy tydzień to warsztat, a nie budowa scenariusza.
Mamy gotowy moduł iFirma w Make, po co ktoś z zewnątrz?
Jeśli wystawiacie jeden rodzaj dokumentu z jednego źródła i to działa, powiemy Wam, żeby tego nie ruszać. Praca zaczyna się przy ponowieniach, korektach, walutach i przy KSeF, bo tam pojedynczy scenariusz bez zapisu stanu robi więcej szkody niż pożytku.
Wystawiamy 30 faktur w miesiącu, to dwie godziny pracy.
Wtedy nie liczy się czas, tylko pomyłka i termin: zły NIP blokuje odliczenie VAT po drugiej stronie, a faktura wystawiona po terminie to rozmowa z biurem rachunkowym. Jeśli na warsztacie wyjdzie, że nie ma czego automatyzować, mówimy to i sprawa kończy się na warsztacie.
Księgowa nie chce, żeby automat dotykał faktur.
Zaczynamy od konta testowego iFirmy z osobnymi kluczami i wyłączoną wysyłką do klientów. Na starcie automat przygotowuje dane, a decyzję o wystawieniu zatwierdza człowiek; próg zatwierdzania zdejmujemy dopiero wtedy, gdy księgowa sama powie, że wystawienia są zgodne.
Musimy być w KSeF i nie wiemy, co to u nas zmienia.
Na warsztacie rozstrzygamy trzy rzeczy: kto wysyła dokument do KSeF, co zapisujemy przy zamówieniu jako potwierdzenie i co się dzieje z dokumentem odrzuconym. Terminy bierzemy z podatki.gov.pl, bo tylko tam są aktualne, a nie z artykułów o KSeF.
- Księgowość i fakturowanie
- iFirma, Fakturownia, Subiekt, Comarch Optima, sevDesk
- CRM
- HubSpot, Pipedrive, Salesforce, LiveSpace
- Sprzedaż i zamówienia
- BaseLinker, Allegro, Shopify, WooCommerce, PrestaShop
- Praca zespołu
- Google Workspace, Microsoft 365, Slack, Notion, ClickUp, Jira, Asana
- Dane i raporty
- BigQuery, Google Sheets, GA4, bazy SQL
- Warstwa automatyzacji
- Make, n8n, Zapier, własne integracje przez API
Operacje w iFirma API i o czym pamiętać przy każdej
Siedem rzeczy, od których zwykle zaczyna się integracja z iFirmą, razem ze sposobem realizacji i pułapką, która przy każdej wraca najczęściej. Wartości liczbowe limitów czytamy z dokumentacji producenta i potwierdzamy w pilocie.
| Operacja | Jak to realizujemy | O czym pamiętać |
|---|---|---|
| Uwierzytelnienie | klucz właściwy dla rodzaju operacji plus podpis liczony z żądania | klucz do faktur nie podpisze żądania z innej grupy; klucze siedzą w sejfie narzędzia, nie w scenariuszu |
| Kontrahent i NIP | sprawdzenie kartoteki po NIP, dane firmy pobrane po numerze, założenie dopiero gdy nie istnieje | kontrahent założony dwa razy to dwie kartoteki i dwa salda; NIP walidujemy przed wywołaniem |
| Wystawienie dokumentu | jedno wywołanie z pozycjami, stawkami VAT, datą sprzedaży i terminem płatności | pola obowiązkowe sprawdzamy u siebie; pozycja bez stawki albo kwota w obcej walucie bez kursu odbija żądanie |
| Jedna faktura na zamówienie | klucz zamówienia sprawdzany przed wywołaniem i zapisany razem z numerem dokumentu | ponowienie po zerwanym połączeniu nie może kończyć się drugim dokumentem; zapisów nie ponawiamy w ciemno |
| Numeracja | numer i identyfikator bierzemy z odpowiedzi iFirmy | numer nadaje iFirma według schematu z panelu, integracja go nie generuje ani nie przewiduje |
| Korekta | osobny dokument korygujący wskazujący fakturę pierwotną | wystawionej faktury nie edytujemy; numer korekty wraca do zamówienia razem z numerem pierwotnym |
| KSeF, PDF i błędy | ustalone miejsce wysyłki do KSeF, potwierdzenie zapisane przy zamówieniu, PDF pobierany po identyfikatorze | dokument utworzony to jeszcze nie dokument wysłany; limity według dokumentacji, sprawdzamy przed wdrożeniem |
Pierwsze wdrożenie obejmuje zwykle wystawianie z jednego źródła, ochronę przed duplikatem i PDF. Korekty, waluty i faktury cykliczne wchodzą tym samym torem, po pomiarze pierwszego etapu.
Jak to robimy
Pięć kroków od panelu iFirmy do integracji na produkcji
Każdy krok kończy się czymś, co możesz ocenić, zanim zdecydujesz o następnym.
Warsztat
Rozkładamy dzisiejsze wystawianie na czynniki: co jest zdarzeniem początkowym, kto wpisuje dane, ile trwa jeden dokument i gdzie powstają pomyłki. Sprawdzamy, jakie systemy już macie, łącznie z arkuszem, w którym ktoś trzyma numery faktur na boku.
Projekt integracji
Zakres kluczy, źródło prawdy o danych nabywcy, pola obowiązkowe dokumentu, klucz chroniący przed duplikatem, ścieżka korekty i miejsce wysyłki do KSeF. Wybór narzędzia: n8n, Make albo własna integracja przez API. Ustalamy, co zapisujemy przy zamówieniu i co ląduje w logu.
Pilot na koncie testowym
Integracja chodzi na osobnym koncie iFirmy z własnymi kluczami i wyłączoną wysyłką do klientów. Przepuszczamy przez nią Wasze prawdziwe zamówienia z ostatnich tygodni, w tym te z obcą walutą, z niepełnym NIP i te, które trafiły do korekty.
Przełączenie i szkolenie
Po akceptacji wystawień przechodzimy na Wasze konto produkcyjne z monitoringiem błędów i alertem o zatrzymanej kolejce. Osoba odpowiedzialna za rozliczenia uczy się czytać kolejkę odrzuceń i sama poprawiać dane, bez zgłoszenia do nas.
Pomiar po 30 i 90 dniach
Patrzymy na liczby, nie na wrażenie: ile dokumentów przeszło bez człowieka, ile odbiło się na walidacji i z jakiego powodu, ile korekt wyszło i czy któraś kategoria błędu wraca. Powtarzalny błąd naprawiamy u źródła danych, a nie łatką w scenariuszu.
Przed i po
Jak zmienia się miesiąc osoby, która rozlicza
Przedtem
- Faktury wystawiane wieczorami z listy zamówień, po jednej, z przepisywaniem danych nabywcy
- Numery pilnowane w arkuszu obok panelu iFirmy, bo tak jest szybciej
- Zły NIP wychodzi po tygodniu, gdy klient odsyła fakturę do poprawy
- PDF wysyłany ręcznie z panelu, a potem szukany w skrzynce, gdy klient go nie widzi
Po zmianie
- Dokument powstaje w kilka sekund po zamknięciu zamówienia, z danymi pobranymi po NIP
- Numer i identyfikator z iFirmy siedzą przy zamówieniu, arkusz przestaje być potrzebny
- Błędne dane odbijają się od walidacji tego samego dnia i mają właściciela zadania
- PDF leży przy zamówieniu i w karcie klienta, a potwierdzenie wysyłki do KSeF też jest zapisane
Pierwsze wystawienia bez człowieka widać w tygodniu przełączenia. Rozkład błędów walidacji i liczbę korekt oceniamy po 30 dniach, a stabilność procesu po 90 dniach.
Dla osoby, która to zamawia
Co z tego ma właściciel albo dyrektor finansowy
Rozliczenia przestają zależeć od jednej osoby i jej wolnego wieczoru. Wystawianie jest procesem, który da się opisać, zatrzymać i odtworzyć, a nie serią decyzji podejmowanych w panelu. Gdy ta osoba jest na urlopie, faktury nadal wychodzą w terminie.
Druga rzecz jest ważniejsza przy rozmowie z biurem rachunkowym i przy kontroli. Wiesz, który dokument powstał z którego zamówienia, kto go zatwierdził i co się z nim stało w KSeF. To ślad, którego przy wystawianiu ręcznym po prostu nie ma.
- Zakres każdego klucza API spisany, klucz wymieniasz bez przebudowy integracji
- Klucz zamówienia chroni przed drugą fakturą za to samo, także po awarii sieci
- Pilot na koncie testowym, więc produkcyjne rozliczenia stoją nietknięte do końca testów
- Log żądań i odpowiedzi, czyli odpowiedź na pytanie „skąd wziął się ten dokument”
Ile to kosztuje
Warsztat ma cenę jawną, integracja wycenę po nim
Warsztat procesowy kosztuje 2500 zł netto za tydzień. Przy jednej integracji fakturowej zwykle wystarcza jeden tydzień, bo proces jest wąski: od zdarzenia w systemie sprzedaży do dokumentu z numerem. Integrację wyceniamy po warsztacie, gdy wiadomo, ile jest źródeł zamówień, ile rodzajów dokumentów i w jakim stanie są dane nabywców.
Abonament iFirmy i koszt narzędzia automatyzacji płacisz bezpośrednio dostawcy, według jego cennika, albo nie płacisz wcale, gdy n8n stoi na Waszej infrastrukturze. Bez naszej prowizji i bez marży na cudzych licencjach.
Warsztat procesowy
2500 zł netto
za tydzień, przy jednej integracji zwykle jeden
Zamknięta całość. Kończy się opisem procesu wystawiania i planem integracji, który możesz zrealizować bez nas albo z inną firmą.
- Mapa dzisiejszego wystawiania razem z miejscami, w których powstają pomyłki
- Zakres kluczy iFirmy i źródło prawdy o danych nabywcy
- Projekt ochrony przed duplikatem i ścieżki korekty
- Ustalenie, kto wysyła dokument do KSeF i co zapisujemy jako potwierdzenie
- Lista pól obowiązkowych dokumentu razem ze wskazaniem, z którego systemu bierze się każde
- Najczęściej wybierany
Warsztat i integracja iFirmy
Wycena po warsztacie
zakres wynika z liczby źródeł i rodzajów dokumentów
Najczęściej wybierany wariant. Działająca integracja w 2 do 4 tygodni od warsztatu, sprawdzona wcześniej na koncie testowym.
- Wszystko z warsztatu
- Wystawianie dokumentów z Waszego źródła zamówień przez n8n, Make albo API
- Kartoteka kontrahenta po NIP, walidacja pól, kolejka odrzuceń
- Numer i PDF wracające do zamówienia, korekty tą samą drogą
- Pilot na koncie testowym, przełączenie z monitoringiem i szkolenie zespołu
Integracja i agent AI do rozliczeń
Wycena po warsztacie
dla firm, które pytają o stan płatności codziennie
Wszystko z integracji plus BOND, firmowy agent AI, który odpowiada na pytania o faktury i wpłaty zwykłym zdaniem.
- Wszystko z integracji iFirmy
- Agent AI spięty z danymi rozliczeń: co niezapłacone, co po terminie, ile korekt
- Alert o zatrzymanej kolejce wystawień i o dokumencie odrzuconym
- Wdrożenie agenta zwykle około 2 miesiące, odpowiedź w 5 do 10 sekund
- Dostęp dla zespołu rozliczeń i dla zarządu, bez logowania do iFirmy
Warsztat kończy się dokumentem, który obroni się bez nas: opisem procesu, zakresem kluczy i planem integracji. Jeśli okaże się, że wystarczy poprawić jeden scenariusz w Make albo że przy Waszej liczbie dokumentów nie ma czego automatyzować, mówimy to wprost i sprawa kończy się na warsztacie.
Najczęstsze pytania
Jak wygląda uwierzytelnianie w API iFirmy?
iFirma nie daje jednego tokenu na wszystko. W panelu generujesz klucz osobno dla faktur, dla rachunków i dla operacji na abonencie, a każde żądanie trzeba podpisać kluczem właściwym dla tej grupy operacji. Klucz do faktur nie podpisze żądania z innej grupy, więc zakres ustalamy przed pierwszym wywołaniem. Sposób liczenia podpisu i nazwy nagłówków bierzemy z dokumentacji na api.ifirma.pl, bo to jedyne źródło, które nie starzeje się w tle.
Czym integracja z iFirmą różni się od integracji z Fakturownią?
Różnicą jest wejście, nie reszta procesu. Fakturownia autoryzuje żądanie tokenem, iFirma wymaga klucza właściwego dla rodzaju operacji i podpisu liczonego z żądania, więc pierwsze połączenie i późniejsza wymiana klucza kosztują trochę więcej pracy. Wszystko, co jest dalej, wygląda tak samo: pola obowiązkowe, ochrona przed duplikatem, numeracja po stronie systemu, korekty i KSeF.
Jak nie wystawić dwóch faktur za to samo zamówienie?
Każde wystawienie dostaje klucz wzięty z zamówienia. Przed wywołaniem sprawdzamy, czy dokument dla tego klucza już istnieje, a po odpowiedzi zapisujemy numer i identyfikator przy zamówieniu. Ponowienie po zerwanym połączeniu trafia wtedy na zapis, a nie na nowy dokument. Zapisów nie ponawiamy w ciemno: ponawiamy odczyty, a wystawienie tylko wtedy, gdy klucz mówi, że dokumentu nie ma.
Kto nadaje numer faktury przy integracji?
iFirma, według schematu numeracji ustawionego w panelu. Integracja nie generuje własnych numerów i nie próbuje ich przewidywać, bo każda taka próba kończy się rozjazdem z rejestrem. Numer i identyfikator dokumentu bierzemy z odpowiedzi i wpisujemy przy zamówieniu, żeby handlowiec, magazyn i księgowa mówili o tym samym papierze.
Co KSeF zmienia w integracji z iFirmą?
Przesuwa koniec procesu. Do tej pory wystarczyło utworzyć dokument i wysłać PDF, teraz liczy się to, czy faktura trafiła do KSeF i z jakim numerem. W integracji oznacza to jedno ustalone miejsce wysyłki, zapisane potwierdzenie przy zamówieniu i osobną ścieżkę dla dokumentu odrzuconego. Obowiązek wszedł 1 lutego 2026 dla największych podatników i 1 kwietnia 2026 dla pozostałych, a aktualny harmonogram i odstępstwa czytamy na podatki.gov.pl.
Co się dzieje, gdy iFirma odrzuci fakturę z powodu danych?
Odrzucenie wraca kodem i komunikatem, a my odkładamy je razem z danymi wejściowymi do kolejki i zakładamy zadanie osobie, która to poprawi. Najczęstsze powody są trzy: NIP z literówką albo nieistniejący, pozycja bez stawki VAT i kwota w obcej walucie bez kursu. Dane, które da się sprawdzić przed wywołaniem, sprawdzamy u siebie, żeby nie zamieniać walidacji iFirmy w system kolejkowy.
Jak wystawiać korekty przez API?
Korekta to osobny dokument, który wskazuje fakturę pierwotną, a nie zmiana w dokumencie już wystawionym. Integracja wystawia ją tą samą drogą co fakturę, z własnym kluczem chroniącym przed duplikatem, i zapisuje numer korekty obok numeru pierwotnego. Dzięki temu przy zamówieniu widać całą historię rozliczenia, także po zwrocie towaru albo zmianie ceny.
Czy da się to przetestować, zanim ruszymy na produkcji?
Tak i tak zawsze zaczynamy. Pilot chodzi na osobnym koncie iFirmy z własnymi kluczami i wyłączoną wysyłką do klientów, a przez integrację przepuszczamy Wasze prawdziwe zamówienia z ostatnich tygodni. Dostępność środowiska testowego i limity zapytań sprawdzamy w dokumentacji na api.ifirma.pl przed wdrożeniem, zamiast zakładać je z góry.
Sprawdźmy, czy Wasze wystawianie da się spiąć z iFirmą
Bezpłatna konsultacja trwa 30 minut. Opowiadasz, skąd biorą się dane do faktury i ile dokumentów wychodzi w miesiącu, a my mówimy, co da się spiąć od razu, co wymaga najpierw uporządkowania kartoteki kontrahentów i gdzie w tym wszystkim siedzi KSeF. Nie musisz na tym etapie udostępniać konta iFirmy ani generować kluczy.
Prowadzimy najwyżej dwa wdrożenia równocześnie, żeby przy każdym ktoś realnie siedział.
Umów bezpłatną konsultacjęPS. Jeśli w tym miesiącu ktoś u Was wystawiał korektę, bo automat zdublował fakturę, to jest dokładnie ten problem. Klucz wzięty z zamówienia i numer zapisany po odpowiedzi kosztują dzień pracy przy wdrożeniu i kończą temat na stałe. Napisz do Pawła, założyciela JustAutomate, i zaczniemy od warsztatu.