# Integracja bez dokumentacji: naprawiać po kimś czy zbudować od nowa? > Skrypt synchronizujący sklep z magazynem napisał ktoś kilka lat temu, dokumentacji nie ma, a każda zmiana to ryzyko. Pokazuję, jak ocenić taką integrację w godzinę, kiedy poprawka ma sens, a kiedy nowa integracja wyjdzie taniej, oraz jak przejąć ją bez przestoju. Adres strony: https://systembox.pl/blog/integracja-bez-dokumentacji-naprawic-czy-od-nowa Autor: Sergiusz Siemak. Opublikowano: 2026-10-21. Kategoria: Automatyzacje. Czas czytania: ok. 8 min. **Integracja bez dokumentacji: naprawiać po kimś czy zbudować od nowa?** Krótka odpowiedź: jeśli integracja działa automatycznie, jest prosta i potrzebujesz jednej zmiany, popraw ją i przy okazji opisz. Jeśli trzeba ją uruchamiać ręcznie, psuje się po aktualizacjach i nikt nie wie, co od niej zależy, nowa integracja często wychodzi szybciej i taniej niż kolejne łatki. Poniżej kryteria, które pozwalają to ocenić. ## Skąd się biorą integracje, których nikt nie rozumie Scenariusz jest prawie zawsze ten sam. Kilka lat temu firma potrzebowała szybko połączyć sklep albo BaseLinker z programem handlowym. Zrobił to informatyk na etacie, znajomy albo mała firma. Działało, więc nikt nie zamawiał opisu. Potem ta osoba odeszła, a integracja została na serwerze jako czarna skrzynka. Dziś każda prośba „dodajmy jeszcze jedno pole” zaczyna się od pytania, czy w ogóle wiadomo, gdzie to zmienić. > **Info:** To nie jest zarzut wobec autora. Integracja zrobiona szybko na konkretną potrzebę to normalna rzecz. Problemem jest brak opisu, a ten zależy od tego, czy ktoś go zamówił i za niego zapłacił. ## Objawy, że integracja stała się ryzykiem - Ktoś musi ją uruchamiać ręcznie, a gdy jest na urlopie, zamówienia albo stany się nie synchronizują. - Po aktualizacji programu handlowego albo sklepu coś przestaje działać i nikt nie wie dlaczego. - Nie ma żadnego zapisu, co integracja przesłała i kiedy, więc błąd wychodzi dopiero przy reklamacji albo inwentaryzacji. - Nie wiadomo, gdzie są hasła i klucze, których używa, ani kto ma do nich dostęp. - Wykonawca, który mógłby ją poprawić, odmawia albo podaje wycenę „po zapoznaniu się z kodem”. ## Jak ocenić integrację w godzinę Do tej oceny nie trzeba być programistą. Wystarczy dostęp do serwera, na którym działa integracja, oraz osoba, która ją obsługuje na co dzień. Odpowiedz na osiem pytań: 1. Czy istnieje jakikolwiek opis: umowa z wykonawcą, instrukcja, korespondencja z ustaleniami? 2. Czy integracja działa sama (harmonogram), czy wymaga uruchomienia przez człowieka? 3. Czy zapisuje dziennik: co przesłała, kiedy i z jakim wynikiem? 4. Czy ktoś dostaje powiadomienie, gdy coś się nie uda? 5. Z ilu plików i jakiego języka się składa, i czy kod jest w repozytorium z historią zmian, czy tylko na serwerze? 6. Jakich danych dostępowych używa i gdzie są zapisane: w kodzie czy w bezpiecznym miejscu? 7. Kiedy ostatnio była zmieniana i czy ktoś pamięta, co wtedy zmieniono? 8. Co dokładnie przestanie działać w firmie, jeśli integracja stanie na dwa dni? Jeśli na większość pytań odpowiedź brzmi „nie wiadomo”, każda zmiana w tej integracji jest ryzykowna, niezależnie od tego, kto ją wykona. ## Kiedy poprawiać, a kiedy budować od nowa **Poprawka czy nowa integracja** Popraw istniejącą, jeśli: - działa automatycznie i rzadko się psuje - kod jest krótki i czytelny, a zmiana dotyczy jednego miejsca - programy po obu stronach nie zmieniają się często - przy okazji poprawki da się ją opisać i dodać powiadomienia o błędach Zbuduj nową, jeśli: - wymaga ręcznego uruchamiania albo pilnowania - psuje się po aktualizacjach programu handlowego lub sklepu - nikt nie wie, co jeszcze od niej zależy - potrzebne są kolejne zmiany, a każda wymaga ponownego rozpracowania kodu Z mojego doświadczenia: gdy integracja powstała bez opisu i była już kilka razy poprawiana przez różne osoby, rozpracowanie jej i bezpieczna poprawka zajmują często tyle czasu, co zbudowanie nowej na sprawdzonych narzędziach. Różnica jest taka, że po nowej zostaje opis, dziennik i powiadomienia, a po poprawce nadal czarna skrzynka, tylko z jedną zmianą więcej. ## Jak przejąć integrację bez zatrzymania sprzedaży 1. Zrób kopię kodu i konfiguracji, zanim cokolwiek zmienisz, i zapisz, gdzie leży. 2. Spisz, co integracja robi dziś: jakie dane, w którą stronę, jak często. To pierwsza strona przyszłej dokumentacji. 3. Przenieś hasła i klucze z kodu do bezpiecznego magazynu i wymień je, jeśli znał je ktoś spoza firmy. 4. Nową integrację uruchom równolegle ze starą na kilka dni i porównuj wyniki, zamiast przełączać wszystko jednego dnia. 5. Starą wyłącz dopiero wtedy, gdy wyniki się zgadzają, i zostaw ją zarchiwizowaną na wypadek, gdyby trzeba było coś sprawdzić. ## Minimum dokumentacji po każdej integracji Żeby za kilka lat nie wrócić do tego samego problemu, przy zamawianiu nowej integracji wpisz do umowy, że wykonawca przekazuje: - opis na jedną lub dwie strony: co integracja robi, w którą stronę idą dane i jak często, - listę pól, które przesyła, z nazwą po obu stronach, - informację, gdzie działa, jak ją uruchomić i zatrzymać oraz gdzie są dane dostępowe, - opis, co się dzieje przy błędzie i kto dostaje powiadomienie, - kod w repozytorium firmy, a nie wyłącznie na serwerze albo u wykonawcy. > **W praktyce:** Dobra dokumentacja integracji jest krótka. Jeśli opis ma pięćdziesiąt stron, nikt go nie przeczyta. Dwie strony, które zrozumie następny informatyk, są warte więcej. ## Pytania i odpowiedzi **Czy da się poprawić integrację bez dokumentacji?** Tak, ale najpierw trzeba ją rozpracować: przejrzeć kod, sprawdzić, jakie dane i kiedy przesyła, i co od niej zależy. Przy prostym, automatycznym skrypcie to szybkie. Przy rozbudowanym, poprawianym przez kilka osób kodzie samo rozpracowanie bywa porównywalne z budową nowej integracji. **Dlaczego wykonawca nie chce poprawiać cudzej integracji?** Bo bierze odpowiedzialność za kod, którego nie zna. Jedna zmiana może zepsuć coś, co działało w innym miejscu. Rzetelny wykonawca zaproponuje najpierw przegląd, a dopiero potem poprawkę albo nową integrację. **Jak uniknąć przestoju przy wymianie integracji?** Uruchomić nową równolegle ze starą na kilka dni, porównywać wyniki i dopiero wtedy wyłączyć starą. Kopię starej integracji warto zachować w archiwum. **Co powinna zawierać dokumentacja integracji?** Krótki opis działania, listę przesyłanych pól, informację, gdzie integracja działa i jak ją uruchomić, opis obsługi błędów oraz kod w repozytorium firmy. Zwykle wystarczą dwie strony. --- SYSTEMBOX Sergiusz Siemak, Białystok. kontakt@systembox.pl, +48 570 923 234 (pn. do pt. 8 do 17). Bezpłatna rozmowa 30 min: https://systembox.pl/umow-rozmowe. Jak wyceniam projekty: https://systembox.pl/jak-wyceniam. Cennik opieki IT: https://systembox.pl/opieka-it. Pełny kontekst: https://systembox.pl/llms-full.txt. Projekty (systemy, integracje, automatyzacje, Recepcja AI) wyceniam indywidualnie po rozmowie. Kwoty opieki IT netto, doliczane 23% VAT.