Integracja przez pliki: gdy system umie tylko eksport CSV albo XML

W artykule o automatyzacji bez API wymieniłem siedem dróg wyjścia, gdy narzędzie nie chce rozmawiać. Jedna wraca w naszych wdrożeniach częściej niż wszystkie pozostałe razem: wymiana plikami. ERP eksportuje CSV, system kadrowy wypluwa XLSX z nieobecnościami, waga przemysłowa zapisuje pomiar na dysk sieciowy, hurtownia wystawia XML z cennikiem na FTP.

To najstarszy wzorzec integracji, jaki istnieje, i w polskich firmach wciąż główny. Duża część naszych wdrożeń z systemami handlowo-księgowymi właśnie od plików się zaczyna, a spora część na nich zostaje na lata. Poniżej rzemiosło: czym przenosić pliki, jak poznać, że plik jest gotowy, co psuje polskie znaki w CSV, jak nie zaksięgować tej samej paczki dwa razy i co zrobić z trzema błędnymi wierszami na tysiąc.

TL;DR: Integracja plikowa jest w porządku, jeśli proces znosi opóźnienie liczone w minutach. O tym, czy przeżyje rok, decydują cztery rzeczy: sygnał, że plik jest kompletny (plik tymczasowy plus zmiana nazwy albo plik-flaga), kodowanie i separator ustalone na sztywno, dedup po sumie kontrolnej pliku i po kluczu rekordu oraz cykliczne porównanie sum. Kanałem wybieraj SFTP, nie mail i nie zwykły FTP.

Dlaczego plik wciąż wygrywa

Eksport do pliku ma praktycznie każdy system, także taki, który powstał, zanim ktokolwiek myślał o REST API. Format wymiany bywa przy tym stabilniejszy niż interfejs programistyczny: aktualizacja ERP potrafi zmienić zachowanie API albo unieważnić token, a układ kolumn w eksporcie zostaje ten sam przez lata. Jest też powód licencyjny: dostęp programistyczny bywa płatnym rozszerzeniem, a eksport plików należy do standardowego wyposażenia. Widać to zarówno przy Optimie i Subiekcie, jak i przy enovie, Symfonii i WAPRO.

„Integracja plikowa ma opinię prowizorki, a w naszych wdrożeniach to zwykle najdłużej działający element całego układu: struktura CSV nie zmienia się przy aktualizacji ERP, a API potrafi. Najczęstsza awaria nie ma zresztą nic wspólnego z formatem. Po prostu plik przestaje przychodzić, a automatyzacja milczy, bo nie ma czego przetwarzać." — Mikołaj Brunka, założyciel NoCodeWork

Zanim pójdziesz dalej, sprawdź, czy naprawdę musisz: zdarza się, że system ma nieudokumentowany interfejs albo gotowy konektor (jak to zweryfikować).

Kanały wymiany: folder, SFTP, mail

Kanał wymiany decyduje o stabilności integracji równie mocno jak format pliku.

Przy folderze sieciowym rozstrzygnij na starcie jedno: n8n w kontenerze albo w chmurze nie zobaczy udziału w firmowym LAN-ie bez zamontowanego wolumenu albo agenta po stronie firmy. Przy FTP wymuś tryb binarny, bo ASCII przepisuje znaki końca linii i po cichu uszkadza plik. Mail traktuj jako ostateczność, z dedykowaną skrzynką i filtrem po nadawcy, nigdy po samym temacie.

Skąd wiedzieć, że plik jest gotowy

Harmonogram to Schedule Trigger, który co kwadrans zagląda do katalogu: nudny i przewidywalny, wystarcza w większości przypadków. Zdarzenie to obserwowanie katalogu na bieżąco, w n8n przez Local File Trigger. Reakcja jest natychmiastowa i właśnie tu czeka pułapka, która wywraca najwięcej wdrożeń.

Nazywa się częściowy zapis. Trigger widzi plik w chwili, gdy system źródłowy dopiero zaczyna go zapisywać. Przy paczce kilkudziesięciu megabajtów zaimportujesz połowę zamówień, a reszta zniknie bez śladu, bo z punktu widzenia automatyzacji wszystko się udało. Na pliku testowym z dwudziestoma wierszami ten błąd nie wystąpi ani razu.

Trzy wzorce, od najlepszego:

• Plik tymczasowy i zmiana nazwy. Nadawca zapisuje dane jako zamowienia.csv.tmp i po zamknięciu pliku zmienia nazwę na zamowienia.csv. Zmiana nazwy w obrębie jednego systemu plików jest atomowa, więc plik pod docelową nazwą jest z definicji kompletny, a automatyzacja reaguje tylko na wzorzec *.csv.
• Plik-flaga. Obok zamowienia.csv pojawia się pusty zamowienia.done, a automat czeka na flagę, nie na dane. Dla systemów, które nie zmienią nazwy, ale zapiszą drugi plik.
• Stabilizacja rozmiaru. Bierzesz plik dopiero wtedy, gdy jego rozmiar i czas modyfikacji nie zmieniły się przez ustalony czas. Najsłabsze, ale często jedyne, gdy nadawcy nie da się o nic poprosić.

Do tego blokada równoległych uruchomień i alert o braku pliku. Automatyzacja, która nie dostała danych, nie zgłosi błędu, bo nie miała czego zepsuć. Regułę „jeśli do 9:00 nie ma pliku z wczoraj, powiadom" trzeba dopisać osobno i to ona wyłapie większość realnych awarii.

CSV: kodowanie, separatory, daty

Kodowanie. Klasyk numer jeden. Starsze systemy eksportują w Windows-1250, nowe w UTF-8, a różnicy nie widać, dopóki nie pojawi się polski znak. Objaw: „Łódź" zamienia się w „£ódŸ" (UTF-8 czytany jako 1250) albo w „Å�ódź" (odwrotnie). Ustal kodowanie w specyfikacji, wymuś je jawnie przy odczycie i przetestuj plik z kompletem polskich znaków. Osobny przypadek to UTF-8 z BOM: parser dokleja wtedy do nazwy pierwszej kolumny niewidzialny znak i mapowanie na Nazwa przestaje trafiać. Jeśli pierwsza kolumna „nie istnieje", choć widzisz ją w pliku, to prawie na pewno to.

Separator i cudzysłowy. W Polsce dominuje średnik, bo tego oczekuje Excel w polskiej lokalizacji, a standard mówi o przecinku: ustal jeden znak i trzymaj się go w obie strony. Pole zawierające separator albo znak nowej linii musi być objęte cudzysłowami, a cudzysłów w środku podwojony, więc nigdy nie dziel wiersza po średniku, tylko używaj prawdziwego parsera CSV. Adres z przecinkiem i uwaga handlowca z enterem w środku to najczęstsze powody, dla których import „nagle" przesuwa kolumny w kilku wierszach na tysiąc.

Daty i liczby. 01.02.2026 to 1 lutego czy 2 stycznia? Zależy, kto generował plik, więc wymuś ISO 8601 (2026-02-01). Przy kwotach ustal kropkę dziesiętną, brak separatora tysięcy i brak waluty w polu wartości. Osobno pilnuj wiodących zer w kodach pocztowych, numerach kont i kodach EAN: jeśli plik przejdzie po drodze przez Excela, zera znikną, a trzynastocyfrowy EAN zamieni się w notację wykładniczą. Dlatego wymiana plikowa nie powinna zawierać przystanku „ktoś otwiera i zapisuje".

XML i Excel: struktura kontra dokument

XML wygrywa tam, gdzie dane mają strukturę zagnieżdżoną: faktura z pozycjami, zamówienie z liniami, pracownik z listą nieobecności. Kodowanie deklaruje wprost w pierwszej linii, więc odpada połowa problemów opisanych wyżej. Nie przypadkiem tą drogą poszły polskie standardy: KSeF operuje na fakturach w XML, JPK też. Dwie rzeczy robią różnicę: walidacja schematem (XSD) przed przetwarzaniem, bo daje komunikat „brakuje elementu X" zamiast błędu gdzieś w środku workflow, oraz przestrzenie nazw, najczęstsza przyczyna tego, że poprawne z wyglądu zapytanie XPath nie zwraca niczego.

Excel jako format wymiany odradzam. XLSX to format dokumentu, nie danych: formuły, scalone komórki, ukryte wiersze i różnica między tym, co widać w komórce, a tym, co w niej siedzi. Data pokazana jako 01.02.2026 bywa liczbą, a komórka z formułą potrafi nie mieć zapisanej wartości, dopóki ktoś nie otworzy pliku.

Jeśli musisz z tym żyć, bo kadry eksportują wyłącznie XLSX, ustal pięć rzeczy: jeden arkusz o stałej nazwie, jeden wiersz nagłówka bez niczego nad nim, zero komórek scalonych, mapowanie kolumn po nazwach zamiast po pozycji i brak formuł w czytanych kolumnach. W n8n odczyt załatwia node Extract from File. Sprawdź też pierwsze bajty: część systemów eksportuje „Excel", który w środku jest HTML-em z rozszerzeniem .xls. A jeśli plik ma być dalej edytowany przez ludzi, to nie integracja, tylko arkusz w roli bazy danych (limity Google Sheets).

Co, gdy ten sam plik przyjdzie dwa razy

Przyjdzie. Ktoś wgra eksport drugi raz, bo nie był pewien, czy pierwszy się udał. Harmonogram po stronie ERP odpali się dwukrotnie po restarcie serwera. Bez idempotencji efektem są podwójne dokumenty w księgowości.

Poziom pliku. Policz sumę kontrolną (SHA-256) zawartości i trzymaj rejestr przetworzonych: nazwa, suma, czas, liczba wierszy, status. Identyczna suma oznacza „już to widziałem": pomiń, ale zapisz zdarzenie i powiadom. Sama nazwa nie wystarczy, bo eksport.csv z poniedziałku wygląda jak ten z wtorku.

Poziom rekordu. Ta warstwa naprawdę ratuje, bo obsługuje przypadek najczęstszy: ten sam plik z jednym poprawionym wierszem. Ustal klucz naturalny (numer dokumentu plus NIP kontrahenta, identyfikator zamówienia, numer pracownika plus okres) i zapisuj przez upsert zamiast przez wstawianie.

Do tego trzy katalogi zamiast jednego: in/, processed/ (z datą w nazwie) i quarantine/. Po przetworzeniu plik przenosisz, nigdy nie kasujesz i nigdy nie zostawiasz na wejściu. Zostawiony plik wejściowy to najczęstsza przyczyna podwójnego przetworzenia, jaką spotykamy w cudzych integracjach.

Tysiąc wierszy, trzy błędne

Pytanie pada w każdym wdrożeniu: odrzucić całość czy przetworzyć 997 dobrych? Wybór zależy od tego, czy wiersze są od siebie zależne.

Próg tolerancji polecam najczęściej: przetwarzaj poprawne wiersze, ale gdy odrzuconych jest więcej niż ustalony odsetek, zatrzymaj cały plik i alarmuj. Trzy błędne wiersze na tysiąc to literówki. Trzysta na tysiąc to nie literówki, tylko ktoś po drugiej stronie zmienił układ eksportu, a Ty właśnie zaimportowałeś siedemset rekordów z danymi w złych polach.

Walidację rozdziel przy tym na dwa etapy. Strukturalna, na poziomie pliku (czy jest nagłówek, czy zgadzają się nazwy kolumn, czy każdy wiersz ma tyle samo pól), przy błędzie oznacza odrzucenie całości. Biznesowa, na poziomie wiersza (czy NIP ma dziesięć cyfr, czy kontrahent istnieje w systemie docelowym), oznacza kwarantannę pojedynczego wiersza wraz z raportem zwrotnym: listą odrzuconych wierszy z powodem, w formie, którą da się otworzyć i poprawić.

Alert musi mieć adresata i treść, bo „workflow failed" wysłane do działu IT nie naprawi literówki w NIP-ie wpisanej w Optimie. Powiadomienie ma trafić do osoby z dostępem do systemu źródłowego i mówić, którego pliku dotyczy, ile wierszy odrzucono i dlaczego.

Rekoncyliacja: cicha utrata danych

Walidacja łapie wiersze, które wyglądają źle. Nie złapie tych, które wyglądają dobrze, a nie powinno ich tam być, ani tych, których zabrakło. Do tego służy cykliczne porównanie sum między systemami. W przejmowanych po kimś integracjach prawie nigdy go nie zastajemy.

Zacznij od stopki pliku. Wiele formatów wymiany, w tym bankowe i komunikaty EDI, kończy plik wierszem z liczbą rekordów i sumą kwot, a niezgodność stopki z tym, co przeczytałeś, wyłapuje ucięty plik natychmiast. Jeśli nadawca stopki nie daje, poproś: po jego stronie to zwykle jedna linijka w szablonie eksportu.

Drugi poziom to raport porównawczy. Codziennie albo raz w tygodniu zestawiaj za ten sam okres liczbę dokumentów w źródle i w celu oraz sumę wartości netto, a rozjazd traktuj jak alert. Wyłapuje to paczkę wgraną dwa razy w odstępie dni, dokumenty wystawione po eksporcie a datowane wstecz i rekordy, które przeszły walidację, a trafiły na złe konto. Raport bez odbiorcy jest bez sensu, więc ustal jedną osobę i jeden dzień w tygodniu.

Dane osobowe w plikach na serwerze

Eksport z systemu kadrowego to zbiór danych osobowych leżący jako plik na dysku. Eksport bazy klientów też. Traktuj katalog wymiany jak bazę danych, bo w praktyce nic nie jest tam tymczasowe.

• Szyfrowany kanał. Zwykły FTP przesyła login, hasło i całą zawartość otwartym tekstem. Minimum to SFTP albo FTPS, najlepiej z logowaniem kluczem.
• Konto techniczne per integracja. Dostęp wyłącznie do swojego katalogu, bez logowania interaktywnego. Nie współdzielone konto „ftp", którego hasło zna pół firmy i były dostawca.
• Minimalizacja zakresu. Najtańsze zabezpieczenie danych to ich nie wyeksportować: jeśli automatyzacja nie używa PESEL-i, nie powinno ich być w pliku.
• Retencja i logi. Ustal, ile dni trzymamy archiwum, i kasuj resztę automatycznie. „Zostawimy na wszelki wypadek" po dwóch latach to katalog z danymi kilku tysięcy osób, o którym nikt nie pamięta.

Stąd uwaga o mailu: załącznik z danymi osobowymi zostaje w skrzynce nadawcy, w Twojej i w kopiach zapasowych obu stron, praktycznie bezterminowo (szerzej o bezpieczeństwie automatyzacji). A jeśli katalog wymiany stoi u zewnętrznego dostawcy albo automatyzację utrzymuje firma z zewnątrz, potrzebna jest umowa powierzenia przetwarzania.

Kiedy pliki to zły pomysł

• Gdy potrzebujesz reakcji w sekundach. Stan magazynowy na sklepie, dostępność terminu, blokada rezerwacji. Plik wymieniany co kwadrans to kwadrans, w którym sprzedajesz towar, którego nie ma.
• Gdy potrzebujesz odpowiedzi zwrotnej. „Czy ta faktura się zaksięgowała i pod jakim numerem?" to pytanie, na które plik nie odpowie. Da się dołożyć plik zwrotny ze statusami, ale to już połowa drogi do prawdziwego interfejsu.
• Gdy ktoś musi ręcznie kliknąć eksport. W piątek po południu, w czasie urlopu i w dniu inwentaryzacji nie kliknie.
• Gdy plik urósł do gigabajtów. Przy takich wolumenach sensowniejsza bywa replikacja bazy.
• Gdy system ma API, a pliki wybiera się z przyzwyczajenia. Zdarza się to częściej, niż myślisz, zwłaszcza gdy integrację projektuje ktoś, kto tak robi od piętnastu lat.

Gdy system nie ma ani API, ani sensownego eksportu, zostaje automatyzacja pulpitu: inna liga pod względem kruchości i kosztów utrzymania (różnice między automatyzacją a RPA). Plik jest niemal zawsze lepszym wyborem, o ile jest dostępny.

FAQ

Czy integracja przez pliki CSV to gorsze rozwiązanie niż API?

Nie z definicji. API wygrywa czasem reakcji, dwukierunkowością i potwierdzaniem operacji. Wymiana plikowa wygrywa dostępnością, odpornością na aktualizacje systemu źródłowego i kosztem wdrożenia. Jeśli proces znosi opóźnienie liczone w minutach, a dane płyną w jedną stronę, plik jest poprawnym rozwiązaniem docelowym, nie prowizorką.

Skąd automatyzacja ma wiedzieć, że plik został zapisany do końca?

Nie zgaduj po samym pojawieniu się pliku w katalogu, bo przeczytasz go w połowie zapisu. Najpewniejszy wzorzec: nadawca zapisuje dane pod nazwą tymczasową (.tmp) i po zamknięciu pliku zmienia nazwę na docelową, a automatyzacja reaguje wyłącznie na docelowy wzorzec nazwy. Alternatywy to plik-flaga albo przetwarzanie dopiero wtedy, gdy rozmiar pliku nie zmienił się przez ustalony czas.

Dlaczego polskie znaki zamieniają się w krzaczki po imporcie CSV?

Prawie zawsze przez rozjazd kodowania: system eksportuje w Windows-1250, a parser czyta jako UTF-8 albo odwrotnie. Objawem jest „£ódŸ" lub „Å�ódź" zamiast „Łódź". Ustal kodowanie w specyfikacji, wymuś je jawnie przy odczycie i przetestuj plik z kompletem polskich znaków. Sprawdź też BOM, bo potrafi doklejać niewidzialne znaki do nazwy pierwszej kolumny.

Co zrobić, gdy w pliku z tysiącem wierszy trzy są błędne?

Zależy od tego, czy wiersze są niezależne. Przy danych powiązanych (faktura z pozycjami) odrzuć cały plik, bo częściowy import zostawi system w niespójnym stanie. Przy wierszach niezależnych (kontrahenci, produkty, godziny pracy) przetwórz poprawne, a błędne odłóż do kwarantanny i wyślij raport zwrotny. Dołóż próg: jeśli odrzuconych jest bardzo dużo, zatrzymaj cały plik, bo to zwykle znaczy, że zmienił się format eksportu.

Czy trzymanie plików z danymi osobowymi na FTP jest zgodne z RODO?

Zwykłego FTP trudno bronić, bo przesyła dane i hasło otwartym tekstem. Wersja do zaakceptowania to SFTP lub FTPS z logowaniem kluczem, osobne konto techniczne ograniczone do jednego katalogu, eksport z tylko niezbędnymi kolumnami, automatyczne kasowanie archiwum i logi dostępu. Jeśli serwer albo automatyzację utrzymuje podmiot zewnętrzny, potrzebna jest umowa powierzenia przetwarzania danych.

Podsumowanie

Wymiana plikami nie jest etapem przejściowym w drodze do „prawdziwej" integracji. W wielu polskich firmach jest integracją docelową i nie ma w tym nic wstydliwego. Różnica między taką, która działa latami, a taką, którą trzeba naprawiać co miesiąc, nie leży w formacie ani w narzędziu, tylko w kilku decyzjach podjętych na starcie: jasny sygnał, że plik jest kompletny; kodowanie, separator i format daty ustalone na sztywno; dedup na poziomie pliku i rekordu; świadomy wybór między odrzuceniem całości a kwarantanną wierszy, zawsze z raportem zwrotnym; cykliczne porównanie sum między systemami; potraktowanie katalogu z plikami jak zbioru danych osobowych, którym w istocie jest. Plus alert, o którym prawie wszyscy zapominają: powiadomienie, gdy plik w ogóle nie przyszedł.

Macie system, który umie tylko eksport do pliku, i zastanawiacie się, czy da się na tym zbudować coś stabilnego? Umów bezpłatną konsultację — przejrzymy Wasz przypadek i powiemy wprost, jeśli sensowniej jest poczekać na normalne API albo zmienić system.

Przeczytaj również

• Jak automatyzować procesy, gdy narzędzie nie ma API
• Comarch Optima i Subiekt: jak podpiąć je pod automatyzacje, też bez API
• enova365, Symfonia, WAPRO: jak podpiąć automatyzacje do polskiego ERP
• Sieć handlowa wymaga EDI: co to znaczy dla dostawcy i ile kosztuje
• Google Sheets w automatyzacjach: kiedy arkusz wystarczy, a kiedy się zemści