Integracja API: jak wygląda wdrożenie i ile kosztuje

Integracja API to połączenie dwóch systemów, w którym jeden program sam pyta drugi o dane albo sam mu je przekazuje, bez eksportu plików i bez przepisywania. Sklep pobiera stany z ERP, zamówienia z Allegro trafiają do sklepu, numer przesyłki wraca do klienta. W tym artykule pokazujemy, czym integracja przez API różni się od wymiany plików XML i CSV oraz od pośrednika, jak radzimy sobie z limitami zapytań i awariami, od czego zaczynamy każde wdrożenie, ile kosztuje integracja systemów u nas i kiedy warto zbudować własne API dla partnerów.

Czym jest integracja API i czym różni się od plików XML, CSV i pośrednika?

API (interfejs programistyczny) to zestaw „drzwi”, przez które jeden program może poprosić drugi o dane albo zlecić mu operację: zapisz zamówienie, zmień cenę, podaj stan magazynu. Odpowiedź przychodzi od razu, z informacją, czy operacja się udała. To najważniejsza różnica w porównaniu z plikami.

W praktyce firmy łączą systemy na trzy sposoby:

Pliki nie są gorszym rozwiązaniem z założenia. Część systemów udostępnia wymianę danych tylko w tej formie. Comarch ERP Optima ma na przykład eksport i import dokumentów przez pliki XML, przy czym opis struktury tych plików jest dostępny wyłącznie dla Autoryzowanych Partnerów Comarch^[1]. Gdy dostawca nie ma API, pracujemy na plikach pobieranych cyklicznie, z mapowaniem kategorii, atrybutów i cen. Gdy API jest, wybieramy je, bo daje kontrolę nad każdą operacją.

Pośrednik to osobna decyzja. Przy kilku kanałach sprzedaży i typowych procesach gotowa platforma bywa tańsza niż cokolwiek pisanego od zera. Porównanie pośrednika z połączeniem bezpośrednim opisujemy szerzej w artykule o integracji Comarch Optima ze sklepem.

Jak działa integracja przez REST API i webhooki?

Większość współczesnych usług udostępnia REST API: program wysyła zapytanie HTTP pod określony adres i dostaje odpowiedź, zwykle w formacie JSON. Tak działa API Allegro, API BaseLinkera i większość API kurierów. Są dwa sposoby, żeby dowiedzieć się o zmianie po drugiej stronie.

• Odpytywanie (polling). Integracja co kilka minut pyta: czy są nowe zamówienia, czy zmieniły się stany. Proste i przewidywalne, ale każde pytanie zużywa limit zapytań, także wtedy, gdy nic się nie zmieniło.
• Webhooki. System, w którym coś się zmieniło, sam wysyła powiadomienie pod ustalony adres: zamówienie opłacone, stan spadł do zera. Szybsze i oszczędniejsze, ale wymaga adresu, który przyjmie powiadomienie, sprawdzi, czy pochodzi od właściwego nadawcy, i zapisze je, zanim zacznie przetwarzanie.

W praktyce często łączymy oba sposoby. W sklepie ALU-GUM ceny i stany idą ze sklepu do Allegro co 5 minut i wysyłane są tylko różnice, a zamówienia z Allegro sklep pobiera co 10 minut^[2]. Wysyłanie samych różnic zamiast całego katalogu sprawia, że integracja mieści się w limitach nawet przy kilku tysiącach ofert.

Co zrobić z limitami zapytań, awariami i ponawianiem?

Każde publiczne API ma limity. Allegro REST API pozwala na 9 000 zapytań na minutę dla jednego Client ID. Po przekroczeniu aplikacja jest blokowana do końca danej minuty i dostaje odpowiedź HTTP 429 Too Many Requests. Niektóre zasoby mają niższe limity, a dla wybranych działa dodatkowy mechanizm ograniczający liczbę zapytań na jednego użytkownika^[3]. API BaseLinkera ma limit 100 zapytań na minutę^[4], czyli dwa rzędy wielkości mniej.

Kod 429 jest zdefiniowany w standardzie RFC 6585. Serwer może dołączyć do niego nagłówek Retry-After, który mówi, ile czekać przed kolejnym zapytaniem^[5]. Słowo „może” jest tu ważne: nie każde API go wysyła, więc integracja musi umieć sama wyliczyć przerwę.

Dlatego w każdej integracji budujemy trzy elementy:

1. Kolejka zadań. Zmiana ceny, nowe zamówienie czy aktualizacja stanu trafia najpierw do kolejki, a dopiero potem jest wysyłana. Jeśli Allegro, hurtownia albo sklep przestaną odpowiadać, zadania czekają, zamiast przepaść.
2. Ponawianie z rosnącym opóźnieniem. Nieudana operacja wraca do kolejki i jest ponawiana po coraz dłuższej przerwie, zgodnej z limitami. Błędy, których ponawianie nie naprawi (np. brak wymaganego parametru oferty), od razu trafiają do osoby, która może je poprawić.
3. Dziennik i alerty. Każda operacja jest zapisana w logu: co, kiedy, z jakim wynikiem. Przy powtarzającym się błędzie wysyłamy alert, zanim klient zauważy, że coś nie działa.

Osobna sprawa to okna czasowe. Przy wymianie sklepu RMC Baltic hosting klienta przestał odpowiadać na około dwie godziny z przyczyn po stronie dostawcy. BaseLinker pytał sklep o zamówienia z ostatnich 3 godzin, więc zamówienie złożone wieczorem nie zostało pobrane. Okno wydłużyliśmy do 72 godzin^[6]. Takie ustawienie przez większość czasu niczego nie zmienia, a w dniu awarii decyduje o tym, czy zamówienie w ogóle dotrze do realizacji.

Od czego zacząć integrację systemów: mapa danych i jedno źródło prawdy

Zanim napiszemy pierwszą linię kodu, robimy mapę danych. Dla każdej danej ustalamy trzy rzeczy: w którym systemie jest jej źródło, kto ma prawo ją zmienić i w którą stronę płynie. Przykład dla sklepu połączonego z ERP i marketplace:

Zasada jednego źródła prawdy brzmi oczywiście, a łamie się ją najczęściej. W ALU-GUM przed naszym projektem ceny i stany żyły w BaseLinkerze. Pod koniec września rozjechały się w całym katalogu, w sklepie i na Allegro, a obsługa poprawiała je ręcznie, oferta po ofercie. Decyzja była taka, że źródłem prawdy dla cen i danych produktowych zostaje sklep, a pośrednik znika z obiegu^[2].

Druga część mapy to wyjątki. Co ma się stać, gdy zamówienie przyjdzie na towar, którego w ERP już nie ma? Gdy cena zmieni się o połowę? Gdy klient poda NIP z literówką? W ALU-GUM zmiana ceny o ponad 25 procent nie idzie na Allegro automatycznie, tylko czeka na potwierdzenie w panelu^[2]. Takie bezpieczniki ustalamy w dokumentacji, zanim zaczniemy programować.

Jak wygląda wdrożenie integracji API krok po kroku?

Nasz proces ma pięć etapów. Opisujemy go też na stronie integracje API dla firm.

1. Mapa danych. Źródło każdej danej, osoba uprawniona do zmiany, kierunek, częstotliwość.
2. Dokumentacja z ceną. Opis połączeń, pól, częstotliwości i wyjątków. Przygotowujemy ją w 2-5 dni roboczych, a cena jest znana przed startem.
3. Kontrakt i testy. Porównujemy wynik integracji z danymi historycznymi. Przy RMC Baltic porównaliśmy 200 zamówień z 75 dni: to, co zapisał sklep, z tym, co odebrał BaseLinker. Narzędzie zwracało jeden z dwóch werdyktów, ZGODNE albo STOP, a testy szły na odciętej kopii, która nie miała czym zapisać danych na koncie klienta^[6].
4. Wdrożenie z nadzorem. Kolejka, ponawianie, limity API, logi i alerty działają od pierwszego dnia, a pierwsze dni obserwujemy na bieżąco.
5. Opieka. Dostawcy API zmieniają swoje interfejsy. Wyłapujemy te zmiany, zanim zatrzymają sprzedaż.

Trzy przykłady z naszych realizacji pokazują, jak różnie może wyglądać zakres:

• ALU-GUM (felgi, Sulmierzyce, ok. 6 tys. felg na stanie): sklep WooCommerce w 5 językach i 4 walutach z kursami NBP. Zamiast BaseLinkera zbudowaliśmy własny hub: Allegro przez API (ceny, stany, zamówienia, wystawianie ofert z karty produktu), Polkurier i Przelewy24. Wyjście z pośrednika zajęło niecałe dwa tygodnie.
• RMC Baltic (części OE, WooCommerce): wymiana sklepu tak, żeby 216 reguł automatyzacji BaseLinkera działało bez zmian. Tu integracja polegała na tym, żeby nowy sklep oddawał zamówienia dokładnie w tym samym kształcie co stary.
• Agropunkt (hurtownia rolnicza, Zator): PrestaShop 9 z ponad 3 000 indeksów, synchronizacja z Comarch Optima (towary i zamówienia), DPD z punktami PUDO i pobraniem, Raben dla wysyłki paletowej.

Ile kosztuje integracja API i ile trwa?

Cena zależy od liczby systemów, liczby kierunków, liczby wyjątków i od tego, czy po drugiej stronie jest porządne API, czy trzeba pracować na plikach. Nasze widełki:

Czas 3-7 dni roboczych liczymy od akceptacji dokumentacji. Najwięcej czasu zajmuje zwykle uporządkowanie danych (brakujące kody EAN, zdublowane towary, różne nazwy tych samych metod dostawy) i testy na prawdziwych zamówieniach, a mniej samo pisanie kodu.

Co podnosi cenę:

• warianty produktów, które w jednym systemie są jedną kartą, a w drugim osobnymi towarami;
• kilka magazynów i kilka cenników, w tym ceny indywidualne dla klientów B2B;
• API bez środowiska testowego albo bez dokumentacji, co wymusza ostrożniejsze testy na kopii;
• migracja z innego rozwiązania w trakcie sprzedaży, jak wyjście z pośrednika.

Po wdrożeniu dochodzi opieka: 200 zł netto za godzinę albo 180 zł netto w stałym pakiecie. Przy większych systemach utrzymanie to zwykle 10-15% wartości rocznie. Kod, dokumentacja i dostęp do repozytorium należą do klienta zgodnie z umową, więc nie jesteś związany z nami na zawsze. Konkretne gotowe ścieżki dla popularnych programów opisujemy osobno: integracja Subiekt GT ze sklepem i integracja Comarch Optima.

Kiedy warto zbudować własne API dla partnerów i co daje OpenAPI?

Tworzenie API po swojej stronie ma sens, gdy to Ty jesteś źródłem danych dla innych: odbiorcy hurtowi chcą pobierać Twój katalog i stany do swoich sklepów, partnerzy chcą składać zamówienia automatycznie, a wysyłanie im plików mailem przestało się skalować. Typowy zakres to REST API z osobnym kluczem dla każdego partnera, limitami zapytań i webhookami o zmianie stanu. Często budujemy je jako część platformy B2B.

Do takiego API zawsze dokładamy dokumentację w standardzie OpenAPI. OpenAPI Specification to niezależny od języka programowania standard opisu interfejsów HTTP, który pozwala ludziom i komputerom poznać możliwości usługi bez dostępu do kodu źródłowego. Aktualna wersja to 3.2.1^[7]. Opis zapisuje się w pliku JSON lub YAML, a na jego podstawie narzędzia generują czytelną dokumentację, szkielety klientów i serwerów w różnych językach oraz testy^[8].

Dla Ciebie oznacza to tyle, że programista partnera nie musi dzwonić z pytaniami o każde pole. Dostaje jeden plik, z którego jego narzędzia same wygenerują dużą część połączenia.

Jak zabezpieczyć integrację API?

Integracja ma dostęp do zamówień, danych klientów i cen, więc jest tak samo ważna dla bezpieczeństwa jak panel administracyjny. Lista OWASP API Security Top 10 z 2023 roku na pierwszym miejscu wymienia błędną autoryzację na poziomie obiektu: każda funkcja, która pobiera dane po identyfikatorze podanym z zewnątrz, musi sprawdzić, czy pytający ma do nich prawo. Na czwartym jest nieograniczone zużycie zasobów, które przy usługach płatnych za zapytanie prowadzi wprost do wyższych rachunków^[9].

Nasze zasady w każdym wdrożeniu:

• Osobny klucz dla każdego systemu i partnera. Gdy współpraca się kończy albo klucz wycieknie, wyłączasz jeden dostęp, a nie całą integrację.
• Najmniejsze potrzebne uprawnienia. Integracja, która tylko czyta stany, nie dostaje prawa zapisu. Środowisko testowe RMC Baltic nie miało wtyczki integracji, kluczy REST ani webhooków, a skrypt importu odrzucał każdą metodę API poza odczytem^[6].
• Klucze poza kodem. Klucze trzymamy poza repozytorium, a hasło do konta nigdy nie trafia do integracji. Allegro w ALU-GUM autoryzujemy kodem do kliknięcia (OAuth 2.0 device flow), bez przekazywania hasła^[2].
• Limity po naszej stronie. Własne API ma limity zapytań na klucz, żeby jeden źle napisany skrypt partnera nie położył sklepu.
• Dane osobowe tylko tam, gdzie są potrzebne. Na serwer testowy nie trafiają dane klientów z zamówień.

Kiedy integracja API nie ma sensu?

Gdy masz kilka zamówień tygodniowo i jeden kanał sprzedaży. Ręczne przepisanie zajmie mniej czasu niż utrzymanie integracji. Gdy gotowy integrator albo pośrednik działa dobrze i nie ogranicza Cię w niczym, zostaw go. Własny hub budujemy wtedy, gdy pośrednik ogranicza procesy albo kosztuje więcej, niż daje.

Nie ma też sensu integrować danych, które są w nieładzie. Integracja przeniesie zdublowane towary i brakujące kody EAN do każdego kanału, tylko szybciej. Najpierw porządek w kartotekach, potem połączenie. Jeśli rozważasz szerszą zmianę, przeczytaj też, jakie procesy w firmie warto zautomatyzować, bo integracja jest zwykle pierwszym krokiem.

Jeśli zastanawiasz się, czy zostać przy pośredniku, czy połączyć sklep z ERP bezpośrednio, przeczytaj porównanie BaseLinker z Optimą: pośrednik czy połączenie bezpośrednie.

Najczęściej zadawane pytania

Jeśli chcesz sprawdzić, jak połączyć Twoje systemy i ile to będzie kosztować, napisz do nas. Odpowiadamy w ciągu 24 godzin, a po krótkiej rozmowie przygotujemy mapę danych i wycenę. Szczegóły zakresu znajdziesz na stronie integracja API i własne API dla partnerów.

Źródła

1. Comarch - Eksport i import dokumentów przez pliki XML (Baza Wiedzy Comarch ERP Optima), dostęp 05.11.2026.
2. KamikStudio - ALU-GUM, sklep z felgami na pięć rynków, dostęp 05.11.2026.
3. Allegro Developer Portal - Informacje podstawowe (limity zapytań), dostęp 05.11.2026.
4. BaseLinker - dokumentacja API, dostęp 05.11.2026.
5. IETF - RFC 6585, Additional HTTP Status Codes, sekcja 4: 429 Too Many Requests, dostęp 05.11.2026.
6. KamikStudio - RMC Baltic, wymiana sklepu z zachowaniem 216 reguł BaseLinkera, dostęp 05.11.2026.
7. OpenAPI Initiative - OpenAPI Specification v3.2.1, dostęp 05.11.2026.
8. Swagger - OpenAPI Specification, dostęp 05.11.2026.
9. OWASP - API Security Top 10 2023, dostęp 05.11.2026.