Zlecenie integracji programiście - brief, zakres i kryteria odbioru

Zlecenie integracji programiście powinno zawierać trzy elementy: brief opisujący cel, systemy i przepływy danych z przykładami, zakres mówiący, co jest w projekcie, a co poza nim, oraz kryteria odbioru, czyli sprawdzalne warunki, po spełnieniu których integracja jest uznana za gotową. Bez tych trzech dokumentów wycena jest zgadywaniem, a odbiór - sporem o to, co było umówione.

W tym wpisie pokazujemy, jak napisać brief integracji sklepu z ERP, marketplace, kurierem czy systemem księgowym, jak opisać zakres, żeby uniknąć nieporozumień, i jak sformułować kryteria odbioru, które da się obiektywnie sprawdzić. Dostajesz gotową strukturę dokumentu i przykłady zapisów, które możesz przenieść do własnego zlecenia, niezależnie od tego, czy zlecasz pracę freelancerowi, agencji czy własnemu programiście.

[#wazne] W skrócie: dobre zlecenie integracji to brief z celem, listą przepływów, systemem nadrzędnym dla każdego typu danych i przykładowymi rekordami, zakres z jasną listą wyłączeń oraz kryteria odbioru zapisane jako konkretne scenariusze testowe. Do tego środowisko testowe, osoba decyzyjna po stronie sklepu i ustalony okres obserwacji po wdrożeniu. Programiści Vinson pomagają przygotować zlecenie integracji i realizują integracje sklepów z ERP, marketplace i innymi systemami.

Jak napisać brief integracji dla programisty

Brief integracji to krótki dokument, który opisuje, jaki problem ma rozwiązać połączenie systemów i jak ma działać z punktu widzenia sklepu. Nie musi zawierać rozwiązań technicznych - od tego jest programista. Musi natomiast odpowiadać na pytania, których programista nie zgadnie: jak wygląda Twój proces, jakie są wyjątki i co jest dla Ciebie najważniejsze. Jeśli dopiero poznajesz temat, podstawy działania połączeń między systemami opisujemy we wpisie integracja API sklepu internetowego - jak to działa.

Dobry brief integracji ma stałą strukturę. Poniższe sekcje wystarczą w większości projektów sklepów internetowych:

Cel biznesowy - co ma się zmienić po wdrożeniu, np. „zamówienia z dwóch marketplace'ów trafiają do ERP bez ręcznego przepisywania”.
Systemy - nazwy i wersje platformy sklepu, ERP, integratora, marketplace'ów, przewoźników, z linkami do dokumentacji API.
Przepływy danych - każdy typ danych w jednym kierunku, z częstotliwością i systemem nadrzędnym.
Reguły i wyjątki - jak traktować rabaty, zestawy, warianty, faktury na firmę, częściowe zwroty.
Przykładowe dane - prawdziwe rekordy, w tym nietypowe przypadki, z danymi osobowymi zanonimizowanymi.
Wymagania niezawodności - co się dzieje, gdy integracja się zatrzyma, kto dostaje alert, jak szybko trzeba reagować.
Osoby i terminy - kto decyduje, kto testuje, kiedy integracja ma działać i czy są okresy, w których nie wolno wdrażać zmian.

Przepływy danych i mapowanie w briefie

Najwięcej nieporozumień rodzi się na styku systemów. Sklep ma statusy zamówień nazwane po swojemu, ERP po swojemu, a marketplace jeszcze inaczej. Dlatego w briefie warto dołączyć tabelę mapowania: jak status, metoda dostawy, stawka VAT czy kategoria z jednego systemu odpowiada wartości w drugim. Nie musi być kompletna - programista ją uzupełni - ale pokaże, że wiesz, gdzie leżą różnice. Szczególnie dużo pracy wymagają warianty produktów, o których piszemy we wpisie warianty produktów w integracjach - jak mapować rozmiary i kolory.

Element	Sklep	ERP	Uwagi
Status zamówienia	Opłacone	Do realizacji	Tylko zamówienia opłacone lub za pobraniem
Metoda dostawy	Paczkomat	Usługa kurierska - kod przewoźnika	Numer punktu w osobnym polu
Stawka VAT	23%	Symbol stawki w ERP	Sprawdzić produkty z obniżoną stawką
Rabat	Kupon na koszyk	Rabat na pozycjach	Rozłożenie proporcjonalne na produkty

Przykładowe dane - jakie rekordy dołączyć

Przykłady są dla programisty cenniejsze niż kilka stron opisu. Pokazują prawdziwą strukturę danych, nazwy pól, formaty dat i kwot oraz przypadki, o których łatwo zapomnieć przy pisaniu briefu. Do zlecenia dołącz eksporty zamówień z każdego kanału, który obejmuje integracja, w tym zamówienia nietypowe: z kilkoma wariantami, z kuponem, z fakturą na firmę, za pobraniem, z paczkomatem, anulowane po opłaceniu i częściowo zwrócone. Dodaj kilka kart produktów z ERP, w tym zestawy i produkty bez EAN. Dane osobowe klientów zanonimizuj albo zastąp fikcyjnymi, zanim wyślesz je wykonawcy - zasady przekazywania danych osobowych skonsultuj z prawnikiem lub inspektorem ochrony danych.

Cały proces zlecenia, od briefu do zamknięcia projektu, warto przejść w ustalonej kolejności. Każdy etap kończy się dokumentem lub decyzją, do której można wrócić:

[#chart:wpr65a]

Zlecenie integracji programiście powinno zawierać trzy elementy: brief opisujący cel, systemy i przepływy danych z przykładami, zakres mówiący, co jest w projekcie, a co poza nim, oraz kryteria odbioru, czyli sprawdzalne warunki, po spełnieniu których integracja jest uznana za gotową. Bez tych trzech dokumentów wycena jest zgadywaniem, a odbiór - sporem o to, co było umówione.

W tym wpisie pokazujemy, jak napisać brief integracji sklepu z ERP, marketplace, kurierem czy systemem księgowym, jak opisać zakres, żeby uniknąć nieporozumień, i jak sformułować kryteria odbioru, które da się obiektywnie sprawdzić. Dostajesz gotową strukturę dokumentu i przykłady zapisów, które możesz przenieść do własnego zlecenia, niezależnie od tego, czy zlecasz pracę freelancerowi, agencji czy własnemu programiście.

[#wazne] W skrócie: dobre zlecenie integracji to brief z celem, listą przepływów, systemem nadrzędnym dla każdego typu danych i przykładowymi rekordami, zakres z jasną listą wyłączeń oraz kryteria odbioru zapisane jako konkretne scenariusze testowe. Do tego środowisko testowe, osoba decyzyjna po stronie sklepu i ustalony okres obserwacji po wdrożeniu. Programiści Vinson pomagają przygotować zlecenie integracji i realizują integracje sklepów z ERP, marketplace i innymi systemami.

Jak napisać brief integracji dla programisty

Brief integracji to krótki dokument, który opisuje, jaki problem ma rozwiązać połączenie systemów i jak ma działać z punktu widzenia sklepu. Nie musi zawierać rozwiązań technicznych - od tego jest programista. Musi natomiast odpowiadać na pytania, których programista nie zgadnie: jak wygląda Twój proces, jakie są wyjątki i co jest dla Ciebie najważniejsze. Jeśli dopiero poznajesz temat, podstawy działania połączeń między systemami opisujemy we wpisie integracja API sklepu internetowego - jak to działa.

Dobry brief integracji ma stałą strukturę. Poniższe sekcje wystarczą w większości projektów sklepów internetowych:

Cel biznesowy - co ma się zmienić po wdrożeniu, np. „zamówienia z dwóch marketplace'ów trafiają do ERP bez ręcznego przepisywania”.
Systemy - nazwy i wersje platformy sklepu, ERP, integratora, marketplace'ów, przewoźników, z linkami do dokumentacji API.
Przepływy danych - każdy typ danych w jednym kierunku, z częstotliwością i systemem nadrzędnym.
Reguły i wyjątki - jak traktować rabaty, zestawy, warianty, faktury na firmę, częściowe zwroty.
Przykładowe dane - prawdziwe rekordy, w tym nietypowe przypadki, z danymi osobowymi zanonimizowanymi.
Wymagania niezawodności - co się dzieje, gdy integracja się zatrzyma, kto dostaje alert, jak szybko trzeba reagować.
Osoby i terminy - kto decyduje, kto testuje, kiedy integracja ma działać i czy są okresy, w których nie wolno wdrażać zmian.

Przepływy danych i mapowanie w briefie

Najwięcej nieporozumień rodzi się na styku systemów. Sklep ma statusy zamówień nazwane po swojemu, ERP po swojemu, a marketplace jeszcze inaczej. Dlatego w briefie warto dołączyć tabelę mapowania: jak status, metoda dostawy, stawka VAT czy kategoria z jednego systemu odpowiada wartości w drugim. Nie musi być kompletna - programista ją uzupełni - ale pokaże, że wiesz, gdzie leżą różnice. Szczególnie dużo pracy wymagają warianty produktów, o których piszemy we wpisie warianty produktów w integracjach - jak mapować rozmiary i kolory.

Element	Sklep	ERP	Uwagi
Status zamówienia	Opłacone	Do realizacji	Tylko zamówienia opłacone lub za pobraniem
Metoda dostawy	Paczkomat	Usługa kurierska - kod przewoźnika	Numer punktu w osobnym polu
Stawka VAT	23%	Symbol stawki w ERP	Sprawdzić produkty z obniżoną stawką
Rabat	Kupon na koszyk	Rabat na pozycjach	Rozłożenie proporcjonalne na produkty

Przykładowe dane - jakie rekordy dołączyć

Przykłady są dla programisty cenniejsze niż kilka stron opisu. Pokazują prawdziwą strukturę danych, nazwy pól, formaty dat i kwot oraz przypadki, o których łatwo zapomnieć przy pisaniu briefu. Do zlecenia dołącz eksporty zamówień z każdego kanału, który obejmuje integracja, w tym zamówienia nietypowe: z kilkoma wariantami, z kuponem, z fakturą na firmę, za pobraniem, z paczkomatem, anulowane po opłaceniu i częściowo zwrócone. Dodaj kilka kart produktów z ERP, w tym zestawy i produkty bez EAN. Dane osobowe klientów zanonimizuj albo zastąp fikcyjnymi, zanim wyślesz je wykonawcy - zasady przekazywania danych osobowych skonsultuj z prawnikiem lub inspektorem ochrony danych.

Cały proces zlecenia, od briefu do zamknięcia projektu, warto przejść w ustalonej kolejności. Każdy etap kończy się dokumentem lub decyzją, do której można wrócić:

[#chart:wpr65a]

Zakres integracji - co jest w projekcie, a co poza nim

Zakres to lista tego, co wykonawca zrobi w ramach zlecenia. Równie ważna jest lista wyłączeń, czyli tego, czego nie zrobi. Zapis „integracja sklepu z ERP” można rozumieć na dziesiątki sposobów. Zapis „przesyłanie nowych zamówień ze sklepu do ERP co 5 minut, aktualizacja stanów z ERP do sklepu co 15 minut, bez obsługi zwrotów i korekt” zostawia niewiele miejsca na interpretację.

Dobrze opisany zakres integracji odpowiada na pytania:

Które przepływy są w projekcie i w jakim kierunku płyną dane?
Jak integracja ma się zachować przy błędzie: ponowić, odłożyć do kolejki, wysłać alert?
Czy w zakresie jest jednorazowe powiązanie istniejących produktów i ofert?
Co z zamówieniami złożonymi przed uruchomieniem integracji?
Czy wykonawca odpowiada za konfigurację po stronie ERP lub marketplace, czy robi to zespół sklepu?
Jaka dokumentacja powstanie i komu zostanie przekazana?
Jak długo trwa okres poprawek po wdrożeniu i co obejmuje?

Lista wyłączeń chroni obie strony. Sklep wie, za co nie zapłacił, a wykonawca, że nie musi robić pracy, której nie wycenił. Jeśli w trakcie projektu pojawi się potrzeba spoza zakresu, staje się osobnym zadaniem z osobną wyceną, a nie źródłem sporu przy odbiorze. Warto od razu ustalić, jak takie zadania będą zgłaszane i wyceniane, żeby nie wstrzymywały głównego projektu i nie przesuwały terminu odbioru.

[#tip] Przy integracjach opartych na zdarzeniach opisz też, co ma się stać, gdy powiadomienie przyjdzie dwa razy albo wcale. Platformy wysyłające webhooki zwykle ponawiają próby przy błędach, więc integracja musi rozpoznawać duplikaty i okresowo sprawdzać, czy nic nie zginęło. Więcej o tym piszemy we wpisie webhooki w e-commerce - do czego służą.

Kryteria odbioru integracji - jak je sformułować

Kryteria odbioru to sprawdzalne warunki, które integracja musi spełnić, żeby uznać pracę za wykonaną. Najlepiej zapisać je jako scenariusze: w jakiej sytuacji, co się dzieje i jaki ma być wynik. Popularny format to „zakładając, że… gdy… wtedy…”. Na przykład: zakładając, że klient zamówił dwa produkty z kuponem 10%, gdy zamówienie zostanie opłacone, wtedy w ERP powstaje dokument z dwiema pozycjami, a rabat jest rozłożony proporcjonalnie na obie.

Scenariusze warto pogrupować według obszarów, tak żeby żaden ważny aspekt integracji nie został pominięty:

[#chart:wpr65b]

Każde kryterium musi być mierzalne. „Integracja działa szybko” nie jest kryterium. „Nowe zamówienie pojawia się w ERP najpóźniej 10 minut po opłaceniu” - jest. „Stany są aktualne” nie jest kryterium. „Zmiana stanu w ERP jest widoczna w sklepie i na marketplace w ciągu 15 minut, a przy stanie zero oferta przestaje być dostępna” - jest. Wartości muszą wynikać z Twoich potrzeb i możliwości systemów, dlatego ustal je razem z wykonawcą jeszcze przed wyceną.

Kto testuje integrację po stronie sklepu

Programista sprawdzi, czy kod działa zgodnie z opisem, ale tylko osoba znająca proces oceni, czy wynik ma sens w codziennej pracy. Wyznacz kogoś z zespołu - najczęściej osobę od obsługi zamówień lub księgowości - kto przejdzie scenariusze odbioru, porówna dokumenty w ERP z zamówieniami i zgłosi uwagi w jednym miejscu. Zarezerwuj tej osobie czas w kalendarzu. Odbiór odkładany tygodniami z braku rąk to jeden z najczęstszych powodów, dla których integracje uruchamiają się później, niż planowano, a wykonawca zdąża w tym czasie zapomnieć szczegóły projektu.

Testy na środowisku testowym i na produkcji

Scenariusze odbioru najpierw sprawdza się w środowisku testowym: na kopii sklepu, testowej bazie ERP i kontach testowych marketplace'ów, jeśli są dostępne. Allegro udostępnia na przykład środowisko sandbox w domenie allegrosandbox.pl z osobnymi kontami testowymi, w którym część funkcji działa inaczej niż na produkcji (stan na sierpień 2026 - sprawdź aktualną dokumentację na developer.allegro.pl). Dlatego po testach na sandboxie i kopii sklepu przychodzi kontrolowane uruchomienie na produkcji, np. na jednym kanale albo na części zamówień, z ręczną weryfikacją pierwszych rekordów. Wyniki każdego scenariusza zapisuj w prostej tabeli: scenariusz, wynik, data, osoba sprawdzająca.

Okres obserwacji po wdrożeniu

Nawet najlepsze testy nie pokażą wszystkich przypadków z prawdziwej sprzedaży. Dlatego w zleceniu warto zapisać okres obserwacji, np. kilka tygodni, w którym wykonawca poprawia błędy wynikające z niezgodności z kryteriami w ramach wynagrodzenia. Ustal też, co jest błędem, a co nową potrzebą: jeśli pojawi się przypadek, którego nie było w briefie ani w scenariuszach, jego obsługa jest zwykle rozszerzeniem zakresu.

Etapy zamiast jednego dużego odbioru

Przy integracjach z wieloma przepływami lepiej podzielić zlecenie na etapy z osobnym odbiorem każdego z nich. Najpierw na przykład zamówienia z marketplace do ERP, potem stany i ceny, na końcu statusy, numery przesyłek i dokumenty. Każdy etap ma własne scenariusze i własny okres obserwacji. Dzięki temu błędy wychodzą na mniejszym fragmencie, zespół sklepu uczy się nowego procesu stopniowo, a wnioski z pierwszego etapu poprawiają brief kolejnych. Jeśli płatności są powiązane z odbiorem etapów, obie strony mają jasny moment rozliczenia i nie czekają na zamknięcie całego projektu.

Najczęstsze problemy przy odbiorze integracji

Problemy przy odbiorze mają zwykle źródło w briefie lub zakresie, a nie w kodzie. Rozpoznanie objawu pozwala szybko znaleźć przyczynę i poprawić proces przy kolejnym zleceniu:

[#chart:wpr65c]

Jak brief i zakres wpływają na wycenę integracji

Wykonawca, który dostaje ogólne zapytanie, ma dwa wyjścia: dopytać o wszystko na kilku spotkaniach albo doliczyć do wyceny zapas na niewiadome. W obu przypadkach płacisz więcej - czasem pracy albo w kwocie oferty. Brief z przepływami, przykładami i kryteriami odbioru pozwala wycenić to, co naprawdę trzeba zrobić, a oferty od różnych wykonawców stają się porównywalne, bo każdy wycenia ten sam zakres.

Jeśli w briefie są elementy, których nie umiesz opisać, np. nie wiesz, czy ERP udostępnia potrzebne dane przez API, zaznacz to wprost. Uczciwy wykonawca zaproponuje wtedy krótką, osobno rozliczaną analizę tego jednego zagadnienia, a resztę wyceni normalnie. To lepsze niż wycena całości obciążona dużym zapasem na ryzyko albo niespodzianka w połowie projektu.

Co przekazać programiście razem ze zleceniem integracji

Poza dokumentami programista potrzebuje dostępu do systemów. Przekaż go w sposób, który pozwoli później łatwo go odebrać: osobne konta lub klucze API z ograniczonymi uprawnieniami zamiast własnego loginu administratora, menedżer haseł zamiast wiadomości e-mail, dostęp do repozytorium należącego do firmy. Dodaj kontakt do dostawców systemów, jeśli integracja wymaga konfiguracji po ich stronie, np. włączenia dostępu do API w ERP.

[#checklista] Razem ze zleceniem przekaż: brief z przepływami i przykładowymi danymi; tabelę mapowania statusów, dostaw i stawek VAT; listę wyłączeń z zakresu; scenariusze odbioru; dostęp do kopii sklepu i testowej bazy ERP; klucze API z ograniczonymi uprawnieniami; dostęp do repozytorium firmy; dane osoby decyzyjnej i osoby testującej; terminy, w których nie wolno wdrażać zmian, np. okres przed Black Friday.

Po odbiorze zadbaj o komplet dokumentacji: opis działania każdego przepływu, miejsce konfiguracji, sposób sprawdzania logów i listę kluczy API z datami ważności. To dokumenty, które pozwolą Twojemu zespołowi albo kolejnemu wykonawcy utrzymać integrację, gdy pierwotny autor nie będzie już dostępny. Zapisy o prawach do kodu i powierzeniu przetwarzania danych osobowych w umowie skonsultuj z prawnikiem.

Jak Vinson pomaga przy zleceniu integracji

Zapewniamy wsparcie programistyczne dla sklepów i sprzedawców: integracje, automatyzacje, poprawki i rozwój sklepów oraz narzędzi. Pomagamy przygotować brief i zakres integracji, rozpisujemy scenariusze odbioru, a potem realizujemy połączenia sklepu z ERP, marketplace'ami, kurierami i systemami księgowymi. Jako certyfikowany partner Base i autoryzowany partner Shoper znamy integracje, z którymi sklepy pracują na co dzień. Szczegóły znajdziesz na stronie Wsparcie programistyczne dla e-commerce.

Najczęściej zadawane pytania

Co powinien zawierać brief integracji dla programisty?

Cel biznesowy, listę systemów z dokumentacją API, przepływy danych z kierunkiem, częstotliwością i systemem nadrzędnym, reguły i wyjątki, przykładowe dane, wymagania niezawodności oraz osoby i terminy. Taki dokument pozwala porównać oferty różnych wykonawców.

Czym są kryteria odbioru integracji?

To sprawdzalne warunki, po spełnieniu których integracja jest uznana za gotową, zapisane jako scenariusze testowe. Każde kryterium musi być mierzalne, np. „zamówienie pojawia się w ERP najpóźniej 10 minut po opłaceniu”, a nie „integracja działa szybko”.

Jak opisać zakres integracji, żeby uniknąć sporów?

Wypisz każdy przepływ danych z kierunkiem i częstotliwością, opisz zachowanie przy błędach i dodaj listę wyłączeń, czyli tego, czego wykonawca nie robi. Potrzeby spoza zakresu, które pojawią się w trakcie, traktuj jako osobne zadania z osobną wyceną.

Gdzie testować integrację przed uruchomieniem?

Na kopii sklepu, testowej bazie ERP i kontach testowych marketplace'ów, jeśli platforma je udostępnia, np. sandbox Allegro. Potem warto uruchomić integrację na produkcji w ograniczonym zakresie i ręcznie sprawdzić pierwsze rekordy.

Co jeśli po odbiorze integracja ma błędy?

Błędy niezgodne z kryteriami odbioru wykonawca zwykle poprawia w okresie obserwacji ustalonym w zleceniu. Przypadki, których nie było w briefie ani scenariuszach, są najczęściej rozszerzeniem zakresu. Dlatego warto zapisać długość okresu poprawek i definicję błędu w umowie.

Dobre zlecenie integracji oszczędza więcej czasu i pieniędzy niż negocjowanie stawki. Jeśli chcesz przygotować brief, zakres i kryteria odbioru dla integracji w swoim sklepie albo zlecić jej wykonanie, sprawdź wsparcie programistyczne Vinson.

Zakres integracji - co jest w projekcie, a co poza nim

Zakres to lista tego, co wykonawca zrobi w ramach zlecenia. Równie ważna jest lista wyłączeń, czyli tego, czego nie zrobi. Zapis „integracja sklepu z ERP” można rozumieć na dziesiątki sposobów. Zapis „przesyłanie nowych zamówień ze sklepu do ERP co 5 minut, aktualizacja stanów z ERP do sklepu co 15 minut, bez obsługi zwrotów i korekt” zostawia niewiele miejsca na interpretację.

Dobrze opisany zakres integracji odpowiada na pytania:

Które przepływy są w projekcie i w jakim kierunku płyną dane?
Jak integracja ma się zachować przy błędzie: ponowić, odłożyć do kolejki, wysłać alert?
Czy w zakresie jest jednorazowe powiązanie istniejących produktów i ofert?
Co z zamówieniami złożonymi przed uruchomieniem integracji?
Czy wykonawca odpowiada za konfigurację po stronie ERP lub marketplace, czy robi to zespół sklepu?
Jaka dokumentacja powstanie i komu zostanie przekazana?
Jak długo trwa okres poprawek po wdrożeniu i co obejmuje?

Lista wyłączeń chroni obie strony. Sklep wie, za co nie zapłacił, a wykonawca, że nie musi robić pracy, której nie wycenił. Jeśli w trakcie projektu pojawi się potrzeba spoza zakresu, staje się osobnym zadaniem z osobną wyceną, a nie źródłem sporu przy odbiorze. Warto od razu ustalić, jak takie zadania będą zgłaszane i wyceniane, żeby nie wstrzymywały głównego projektu i nie przesuwały terminu odbioru.

[#tip] Przy integracjach opartych na zdarzeniach opisz też, co ma się stać, gdy powiadomienie przyjdzie dwa razy albo wcale. Platformy wysyłające webhooki zwykle ponawiają próby przy błędach, więc integracja musi rozpoznawać duplikaty i okresowo sprawdzać, czy nic nie zginęło. Więcej o tym piszemy we wpisie webhooki w e-commerce - do czego służą.

Kryteria odbioru integracji - jak je sformułować

Kryteria odbioru to sprawdzalne warunki, które integracja musi spełnić, żeby uznać pracę za wykonaną. Najlepiej zapisać je jako scenariusze: w jakiej sytuacji, co się dzieje i jaki ma być wynik. Popularny format to „zakładając, że… gdy… wtedy…”. Na przykład: zakładając, że klient zamówił dwa produkty z kuponem 10%, gdy zamówienie zostanie opłacone, wtedy w ERP powstaje dokument z dwiema pozycjami, a rabat jest rozłożony proporcjonalnie na obie.

Scenariusze warto pogrupować według obszarów, tak żeby żaden ważny aspekt integracji nie został pominięty:

[#chart:wpr65b]

Każde kryterium musi być mierzalne. „Integracja działa szybko” nie jest kryterium. „Nowe zamówienie pojawia się w ERP najpóźniej 10 minut po opłaceniu” - jest. „Stany są aktualne” nie jest kryterium. „Zmiana stanu w ERP jest widoczna w sklepie i na marketplace w ciągu 15 minut, a przy stanie zero oferta przestaje być dostępna” - jest. Wartości muszą wynikać z Twoich potrzeb i możliwości systemów, dlatego ustal je razem z wykonawcą jeszcze przed wyceną.

Kto testuje integrację po stronie sklepu

Programista sprawdzi, czy kod działa zgodnie z opisem, ale tylko osoba znająca proces oceni, czy wynik ma sens w codziennej pracy. Wyznacz kogoś z zespołu - najczęściej osobę od obsługi zamówień lub księgowości - kto przejdzie scenariusze odbioru, porówna dokumenty w ERP z zamówieniami i zgłosi uwagi w jednym miejscu. Zarezerwuj tej osobie czas w kalendarzu. Odbiór odkładany tygodniami z braku rąk to jeden z najczęstszych powodów, dla których integracje uruchamiają się później, niż planowano, a wykonawca zdąża w tym czasie zapomnieć szczegóły projektu.

Testy na środowisku testowym i na produkcji

Scenariusze odbioru najpierw sprawdza się w środowisku testowym: na kopii sklepu, testowej bazie ERP i kontach testowych marketplace'ów, jeśli są dostępne. Allegro udostępnia na przykład środowisko sandbox w domenie allegrosandbox.pl z osobnymi kontami testowymi, w którym część funkcji działa inaczej niż na produkcji (stan na sierpień 2026 - sprawdź aktualną dokumentację na developer.allegro.pl). Dlatego po testach na sandboxie i kopii sklepu przychodzi kontrolowane uruchomienie na produkcji, np. na jednym kanale albo na części zamówień, z ręczną weryfikacją pierwszych rekordów. Wyniki każdego scenariusza zapisuj w prostej tabeli: scenariusz, wynik, data, osoba sprawdzająca.

Okres obserwacji po wdrożeniu

Nawet najlepsze testy nie pokażą wszystkich przypadków z prawdziwej sprzedaży. Dlatego w zleceniu warto zapisać okres obserwacji, np. kilka tygodni, w którym wykonawca poprawia błędy wynikające z niezgodności z kryteriami w ramach wynagrodzenia. Ustal też, co jest błędem, a co nową potrzebą: jeśli pojawi się przypadek, którego nie było w briefie ani w scenariuszach, jego obsługa jest zwykle rozszerzeniem zakresu.

Etapy zamiast jednego dużego odbioru

Przy integracjach z wieloma przepływami lepiej podzielić zlecenie na etapy z osobnym odbiorem każdego z nich. Najpierw na przykład zamówienia z marketplace do ERP, potem stany i ceny, na końcu statusy, numery przesyłek i dokumenty. Każdy etap ma własne scenariusze i własny okres obserwacji. Dzięki temu błędy wychodzą na mniejszym fragmencie, zespół sklepu uczy się nowego procesu stopniowo, a wnioski z pierwszego etapu poprawiają brief kolejnych. Jeśli płatności są powiązane z odbiorem etapów, obie strony mają jasny moment rozliczenia i nie czekają na zamknięcie całego projektu.

Najczęstsze problemy przy odbiorze integracji

Problemy przy odbiorze mają zwykle źródło w briefie lub zakresie, a nie w kodzie. Rozpoznanie objawu pozwala szybko znaleźć przyczynę i poprawić proces przy kolejnym zleceniu:

[#chart:wpr65c]

Jak brief i zakres wpływają na wycenę integracji

Wykonawca, który dostaje ogólne zapytanie, ma dwa wyjścia: dopytać o wszystko na kilku spotkaniach albo doliczyć do wyceny zapas na niewiadome. W obu przypadkach płacisz więcej - czasem pracy albo w kwocie oferty. Brief z przepływami, przykładami i kryteriami odbioru pozwala wycenić to, co naprawdę trzeba zrobić, a oferty od różnych wykonawców stają się porównywalne, bo każdy wycenia ten sam zakres.

Jeśli w briefie są elementy, których nie umiesz opisać, np. nie wiesz, czy ERP udostępnia potrzebne dane przez API, zaznacz to wprost. Uczciwy wykonawca zaproponuje wtedy krótką, osobno rozliczaną analizę tego jednego zagadnienia, a resztę wyceni normalnie. To lepsze niż wycena całości obciążona dużym zapasem na ryzyko albo niespodzianka w połowie projektu.

Co przekazać programiście razem ze zleceniem integracji

Poza dokumentami programista potrzebuje dostępu do systemów. Przekaż go w sposób, który pozwoli później łatwo go odebrać: osobne konta lub klucze API z ograniczonymi uprawnieniami zamiast własnego loginu administratora, menedżer haseł zamiast wiadomości e-mail, dostęp do repozytorium należącego do firmy. Dodaj kontakt do dostawców systemów, jeśli integracja wymaga konfiguracji po ich stronie, np. włączenia dostępu do API w ERP.

[#checklista] Razem ze zleceniem przekaż: brief z przepływami i przykładowymi danymi; tabelę mapowania statusów, dostaw i stawek VAT; listę wyłączeń z zakresu; scenariusze odbioru; dostęp do kopii sklepu i testowej bazy ERP; klucze API z ograniczonymi uprawnieniami; dostęp do repozytorium firmy; dane osoby decyzyjnej i osoby testującej; terminy, w których nie wolno wdrażać zmian, np. okres przed Black Friday.

Po odbiorze zadbaj o komplet dokumentacji: opis działania każdego przepływu, miejsce konfiguracji, sposób sprawdzania logów i listę kluczy API z datami ważności. To dokumenty, które pozwolą Twojemu zespołowi albo kolejnemu wykonawcy utrzymać integrację, gdy pierwotny autor nie będzie już dostępny. Zapisy o prawach do kodu i powierzeniu przetwarzania danych osobowych w umowie skonsultuj z prawnikiem.

Jak Vinson pomaga przy zleceniu integracji

Zapewniamy wsparcie programistyczne dla sklepów i sprzedawców: integracje, automatyzacje, poprawki i rozwój sklepów oraz narzędzi. Pomagamy przygotować brief i zakres integracji, rozpisujemy scenariusze odbioru, a potem realizujemy połączenia sklepu z ERP, marketplace'ami, kurierami i systemami księgowymi. Jako certyfikowany partner Base i autoryzowany partner Shoper znamy integracje, z którymi sklepy pracują na co dzień. Szczegóły znajdziesz na stronie Wsparcie programistyczne dla e-commerce.

Najczęściej zadawane pytania

Co powinien zawierać brief integracji dla programisty?

Cel biznesowy, listę systemów z dokumentacją API, przepływy danych z kierunkiem, częstotliwością i systemem nadrzędnym, reguły i wyjątki, przykładowe dane, wymagania niezawodności oraz osoby i terminy. Taki dokument pozwala porównać oferty różnych wykonawców.

Czym są kryteria odbioru integracji?

To sprawdzalne warunki, po spełnieniu których integracja jest uznana za gotową, zapisane jako scenariusze testowe. Każde kryterium musi być mierzalne, np. „zamówienie pojawia się w ERP najpóźniej 10 minut po opłaceniu”, a nie „integracja działa szybko”.

Jak opisać zakres integracji, żeby uniknąć sporów?

Wypisz każdy przepływ danych z kierunkiem i częstotliwością, opisz zachowanie przy błędach i dodaj listę wyłączeń, czyli tego, czego wykonawca nie robi. Potrzeby spoza zakresu, które pojawią się w trakcie, traktuj jako osobne zadania z osobną wyceną.

Gdzie testować integrację przed uruchomieniem?

Na kopii sklepu, testowej bazie ERP i kontach testowych marketplace'ów, jeśli platforma je udostępnia, np. sandbox Allegro. Potem warto uruchomić integrację na produkcji w ograniczonym zakresie i ręcznie sprawdzić pierwsze rekordy.

Co jeśli po odbiorze integracja ma błędy?

Błędy niezgodne z kryteriami odbioru wykonawca zwykle poprawia w okresie obserwacji ustalonym w zleceniu. Przypadki, których nie było w briefie ani scenariuszach, są najczęściej rozszerzeniem zakresu. Dlatego warto zapisać długość okresu poprawek i definicję błędu w umowie.

Dobre zlecenie integracji oszczędza więcej czasu i pieniędzy niż negocjowanie stawki. Jeśli chcesz przygotować brief, zakres i kryteria odbioru dla integracji w swoim sklepie albo zlecić jej wykonanie, sprawdź wsparcie programistyczne Vinson.

Zlecenie integracji programiście - brief, zakres i kryteria odbioru