API w systemach ERP i CRM: co sprawdzić w dokumentacji dostawcy

Od czego zacząć przegląd dokumentacji API

Przed przeglądem metod i nagłówków ustal procesy objęte integracją oraz system źródłowy dla każdego zbioru. CRM zwykle obsługuje sprzedaż, marketing i obsługę klienta (front-office). ERP odpowiada za finanse, księgowość, magazyn, produkcję oraz kadry i płace (back-office). Systemy często współpracują, a CRM dostarcza ERP dane o klientach i transakcjach (2N).

W architekturze paszportu produktu (Tandemite) ERP pozostaje systemem referencyjnym dla zakupów, transakcji, dostawców, zleceń i ewidencji partii. Dokumentacja konstrukcyjna i jej wersje mogą pochodzić z PLM, a dane o rzeczywistym wykonaniu produktu z systemu obsługującego produkcję. Najpierw rozstrzygnij, kto jest właścicielem którego zbioru danych.

Ustal model wdrożenia, bo wyznacza odpowiedzialność za infrastrukturę. Microsoft Dynamics 365 Business Central jest opisywany jako rozwiązanie cloud-first, dostępne w chmurze SaaS na platformie Azure oraz lokalnie. SAP Business One oferuje wdrożenie lokalne, w chmurze partnera lub hybrydowo, na MS SQL albo SAP HANA (Supremis).

W chmurze infrastrukturę techniczną zapewnia dostawca oprogramowania, a firma ustala zakres uprawnień i sposób korzystania z danych (Livespace). Spisz listę obiektów, kierunek przepływu (ERP do CRM, CRM do ERP, dwukierunkowo), wymaganą częstotliwość synchronizacji i właściciela każdego zbioru. Do niej dopasuj opisy w dokumentacji API.

Uwierzytelnianie, tokeny i zarządzanie dostępem

Sprawdź metody identyfikacji wymienione w dokumentacji. Dla Business Central opisywane jest uwierzytelnianie m.in. przez konto Windows (Active Directory) i konto Microsoft 365 (Azure Active Directory). Uwierzytelnianie wieloskładnikowe można stosować do usług stacjonarnych i online, a po uwierzytelnieniu system sprawdza uprawnienia do raportów, dokumentów i zasobów sieciowych (NMI ERP).

Ogólny porządek dostępu w ERP to identyfikacja, uwierzytelnienie i dwustopniowa autoryzacja. Towarzyszy mu wymuszanie regularnej zmiany haseł oraz odpowiedniej długości i zróżnicowania znaków (NMI ERP). W dokumentacji API szukaj odpowiednika tych mechanizmów: typu tokenu, czasu życia, odświeżania, unieważniania oraz tego, czy konto integracyjne podlega uwierzytelnianiu wieloskładnikowemu.

Osobny przypadek to dostęp przez konto w zewnętrznym serwisie. W integracji Comarch e-Sale z Allegro token REST API pobiera się w panelu administracyjnym przyciskiem „pobierz”, następnie loguje się w serwisie i wyraża wymagane zgody (Comarch). Token jest związany z kontem i zgodami po stronie platformy zewnętrznej. Ustal, co się dzieje po zmianie hasła, odebraniu zgody lub usunięciu konta oraz kto w firmie zarządza tym kontem.

Sprawdź, czy dokumentacja przewiduje osobne konto techniczne i jak opisuje nadawanie uprawnień. Zasada w ERP: każdy użytkownik powinien korzystać wyłącznie z funkcji i danych niezbędnych w codziennej pracy, a uprawnienia nadaje administrator wewnątrz firmy (NMI ERP). Jeśli API korzysta z tego samego mechanizmu uprawnień co interfejs użytkownika, konto integracyjne dziedziczy role. Warto, by miało własną, wąską rolę zamiast uprawnień administracyjnych — nadmiarowe uprawnienia zwiększają skutki ewentualnego wycieku tokenu.

Porównanie modeli wdrożenia: Microsoft Dynamics 365 Business Central vs SAP Business One

Zakres danych i dostępne operacje

Wypisz obiekty z dokumentacji i porównaj je z listą procesów z pierwszego kroku. W integracji Comarch e-Sale z Allegro występują m.in.: konta Allegro, zamówienia, kontrola stanów magazynowych, klienci, ceny, szablony ofert, oferty, obsługa parametrów zależnych w ofercie oraz numer listu przewozowego. W opisie integracji ERP z paszportem produktu wymieniane są produkty, komponenty, dostawcy, partie, transakcje, zlecenia i produkcyjne zestawienie komponentów (BOM) (Tandemite).

To zestawienie podpowiada kolejne pytania: czy obiekt jest tylko do odczytu, czy również do zapisu, aktualizacji i usunięcia oraz czy przewidziano operacje masowe.

Drugi krok to mapowanie pól. Dokumentacja powinna wskazywać identyfikator łączący rekordy między systemami — w Comarch e-Sale jednym z opisanych mechanizmów jest automatyczne powiązanie towarów z ofertami po kodzie EAN. Przy integracjach produktowych mapowanie i przekształcanie danych bywa realizowane w warstwie pośredniej: Pimcore udostępnia narzędzia do importu, mapowania i przekształcania danych oraz kontrolowania ich publikacji (Tandemite).

Ustal, jakie jednostki, formaty daty, waluty i słowniki statusów przyjmuje API. Każda różnica między systemami wymaga zdefiniowanego miejsca przekształcenia, inaczej rozbieżności ujawnią się na danych produkcyjnych.

Przykładowe obiekty dostępne w API (comarch e-Sale + Allegro)

Wersjonowanie, zmiany i cykl życia interfejsu

Sprawdź, czy dokumentacja podaje numer wersji API i sposób przejścia na nowszą. W Comarch e-Sale od wersji 2019.3 dostępne jest nowe REST API Allegro, a klienci korzystający ze starego interfejsu mogą się przełączyć, pobierając token REST API w panelu administracyjnym. To samo źródło podaje, że Allegro wyłączyło obsługę WebAPI od 13 stycznia 2020 roku, a od wersji 2020.0 e-Sale w pełni obsługuje Allegro REST API.

O terminie wygaszenia interfejsu może zdecydować nie tylko dostawca ERP, ale też zewnętrzna platforma. W dokumentacji szukaj changelogu, polityki wygaszania starszych metod i informacji o okresie równoległego wsparcia obu wersji.

Zapytaj, kto decyduje o momencie aktualizacji. Microsoft Dynamics 365 Business Central jest opisywany jako system nastawiony na automatyczne aktualizacje i wbudowaną sztuczną inteligencję, a SAP Business One — na stabilność i precyzyjne dopasowanie branżowe (Supremis).

To dwa modele ryzyka. Przy automatycznych aktualizacjach liczy się, jak dostawca komunikuje zmiany w API i czy przestarzałe zasoby są wygaszane bez decyzji firmy. Przy wdrożeniu lokalnym — kto instaluje nową wersję i powtarza testy integracji po aktualizacji.

Wygaśnięcie interfejsów: przykład z Allegro

Środowisko testowe i konfiguracja po stronie systemu

Środowisko testowe powinno być opisane równie konkretnie jak produkcyjne. W Comarch e-Sale przy dodawaniu konta Allegro występuje parametr „Tryb testowy”, który zaznacza się, jeśli konto założono w serwisie testowym Allegro. Przycisk logowania przekierowuje do serwisu, a po zalogowaniu konto zostaje przyłączone do panelu administracyjnego i aplikacja pobiera dane.

Od wersji 2020.3 konto w trybie testowym dodaje się według aktualnie zalogowanego użytkownika w innej zakładce przeglądarki, a przy dodawaniu pojawia się pytanie, czy dodać aktualnie zalogowane konto (Comarch).

Przed uruchomieniem zapytaj: czy środowisko testowe to odrębna instancja i baza, czy tylko tryb w systemie produkcyjnym; czy dane testowe są izolowane od rzeczywistych; czy token i konto testowe są oddzielne od produkcyjnych; czy testy można wykonać samodzielnie, bez konsultanta; i co dzieje się z sesją przeglądarki, gdy logowanie odbywa się przez przekierowanie do zewnętrznego serwisu.

Ustal, które ustawienia integracji są dostępne w panelu administracyjnym i które można wyłączyć przed startem produkcyjnym. W Comarch e-Sale są to m.in. automatyczne tworzenie zamówień do ofert, kontrola stanów magazynowych, automatyczne wznawianie ofert i decyzja, czy ceny na ofertach mają zmieniać się automatycznie po zmianie ceny w sklepie.

Obsługa błędów, ponowienia i kolejkowanie

Zakres odpowiedzialności za błędy bywa rozdzielony między API a warstwę integracyjną. W opisie integracji ERP z paszportem produktu transport danych, kolejki komunikatów i ponawianie nieudanych operacji są wprost przypisane do warstwy integracyjnej, a nie do samego ERP (Tandemite).

Dostawca ERP może nie oferować gotowej kolejki ani mechanizmu ponowień. Sprawdź, czy dokumentacja je opisuje, czy milcząco zakłada, że zbudujesz je po swojej stronie.

Z dokumentacji powinno wynikać, jakie kody błędów zwraca API i co oznaczają. Sprawdź, czy odpowiedź zawiera identyfikator żądania pozwalający powiązać ją z logami, czy operacje są idempotentne — czyli czy ponowienie tego samego żądania nie utworzy drugiego zamówienia lub dokumentu — oraz jakie obowiązują limity liczby zapytań.

Brak tych informacji oznacza, że pierwszy scenariusz awaryjny będzie testowany na produkcji. Ustal również, gdzie trafiają logi wywołań API i jak długo są przechowywane; bez tego nie odtworzysz sytuacji, w której ten sam dokument powstał dwukrotnie.

Bezpieczeństwo transmisji i przechowywania danych

Sprawdź, czy dokumentacja potwierdza szyfrowanie przesyłanych danych oraz jaki poziom zabezpieczeń stosuje się do baz danych i kopii zapasowych. NMI ERP wskazuje te elementy jako kluczowe przy ocenie systemu ERP, obok używania certyfikowanych technologii zabezpieczania i przechowywania danych.

To samo źródło podkreśla, że bezpieczeństwo systemu ERP powinno być zgodne z polityką bezpieczeństwa całej infrastruktury IT firmy, a za poprawne uruchomienie mechanizmów bezpieczeństwa odpowiada zespół wdrażający. Zapisz w projekcie, kto weryfikuje konfigurację po uruchomieniu.

W modelu chmurowym część odpowiedzialności przechodzi na dostawcę: infrastrukturę techniczną zapewnia dostawca oprogramowania, a firma kształtuje uprawnienia i określa, jak wykorzystuje dane (Livespace). Mechanizmy wskazywane dla CRM to szyfrowanie transmisji oraz zabezpieczenia przed nieautoryzowanym dostępem (Livespace). Osobne pytanie dotyczy spójności kanałów: czy API używa tych samych mechanizmów co interfejs użytkownika, czy obsługuje je inna infrastruktura z własnym uwierzytelnianiem i kopiami zapasowymi.

Ślad audytowy, historia zmian i uprawnienia przez API

Dla danych osobowych dokumentacja powinna przewidywać zapis, kto i kiedy dokonał zmiany. NMI ERP wskazuje, że każda modyfikacja danych osobowych powinna być zapisana wraz z datą i informacją o osobie dokonującej zmiany. Wśród funkcji CRM wspierających zgodność wymienia się historię aktywności i zmian danych osobowych (Livespace), a w opisie monitorowania przetwarzania — zapis daty i godziny utworzenia kartoteki kontrahenta oraz pełną historię każdej edycji danych (Synergius CRM).

Pytanie brzmi, czy te mechanizmy obejmują operacje wykonane przez API. Jeśli konto integracyjne jest jednym z użytkowników systemu, w historii zmian może figurować jako autor wszystkich modyfikacji, co uniemożliwia ustalenie, z którego procesu pochodzi zmiana.

Sprawdź, czy dokumentacja opisuje przekazywanie tożsamości użytkownika końcowego w wywołaniach API i czy da się oddzielić uprawnienia konta integracyjnego od uprawnień ludzi. Zasada jest stała: każdy użytkownik korzysta tylko z funkcji i danych niezbędnych do pracy, a uprawnienia nadaje administrator wewnątrz firmy (NMI ERP).

Obsługa danych osobowych, zgód i żądań osób

RODO nakłada obowiązek ochrony danych osobowych na każdym etapie przetwarzania, w tym danych w CRM: wskazania administratora danych, informowania o podstawie i celu przetwarzania, ograniczenia dostępu do osób upoważnionych, umożliwienia realizacji praw osób (dostępu, sprostowania, usunięcia) oraz przechowywania danych tylko przez okres niezbędny do realizacji celu (Livespace).

W projekcie integracji rozstrzygnij role: procesor przetwarza dane na zlecenie administratora — przechowuje, organizuje, modyfikuje, udostępnia, niszczy lub usuwa — nie decydując o celu i sposobach przetwarzania (Synergius CRM). Od tego podziału zależą obowiązki po każdej stronie i ich zapis w umowie.

Z perspektywy API kluczowe są funkcje, które dokumentacja powinna opisywać wprost: rejestr zgód i podstaw przetwarzania danych, mechanizmy usuwania danych na żądanie klientów, zarządzanie dokumentami i zgodami oraz role i procedury dostępu (Livespace).

Sprawdź, czy przez API można wyeksportować dane osoby, skorygować je oraz usunąć lub zanonimizować; czy trzeba to robić ręcznie w interfejsie i jak udokumentować wykonanie takiego żądania.

Osobnej uwagi wymagają dane szczególnych kategorii — RODO wymienia m.in. pochodzenie rasowe i etniczne, poglądy polityczne, przekonania religijne i światopoglądowe, przynależność do związków zawodowych oraz stan zdrowia i co do zasady zabrania ich przetwarzania (Synergius CRM). Jeśli CRM gromadzi takie informacje w polach opisowych, zakres pól udostępnianych przez API powinien być świadomie ograniczony.

Sprawdź też, jak dostawca reaguje na zmiany regulacyjne. ITrix wskazuje, że w 2025 roku firmy muszą przygotować się na bardziej szczegółowe wymagania dotyczące bezpieczeństwa danych osobowych i przechowywania danych klientów, obejmujące większą kontrolę nad przetwarzaniem danych w CRM, obowiązkowe audyty i monitorowanie aktywności, przy dotkliwszych karach za naruszenia.

To deklaracja dostawcy, nie treść przepisu — traktuj ją jako podstawę do pytań, które elementy API wspierają monitorowanie aktywności i dokumentowanie audytu. Dla porządku: definicja danych osobowych obejmuje informacje o osobie zidentyfikowanej lub możliwej do zidentyfikowania, w tym identyfikator internetowy (art. 4 ust. 1 RODO, za Synergius CRM), a RODO stosuje się od 25 maja 2018 r. (Synergius CRM) — identyfikatory wykorzystywane w integracjach również podlegają tym zasadom.

Zalety i wady integracji przez API w kontekście RODO

Współpraca z innymi systemami i wzorce integracji

Dokumentację API oceniaj w kontekście całego krajobrazu systemów, nie pojedynczego wdrożenia. CRM i ERP zwykle współpracują: CRM dostarcza ERP danych o klientach i transakcjach, a część platform, jak Microsoft Dynamics 365, łączy funkcje CRM i ERP w jednym środowisku (2N).

Model łańcucha danych przy paszporcie produktu wygląda tak: ERP, PLM, dane dostawców, dokumentacja i wyniki analiz środowiskowych trafiają do warstwy integracyjnej, z niej do systemu PIM, a następnie do usługi DPP. Identyfikatory i wymagane dane rejestracyjne trafiają do rejestru UE, a identyfikator umieszcza się na produkcie lub opakowaniu, na przykład jako kod QR z adresem zgodnym z GS1 Digital Link (Tandemite).

Z tego opisu wynikają dwa wzorce do sprawdzenia u każdego dostawcy. Pierwszy to warstwa integracyjna jako bufor: ERP pozostaje systemem referencyjnym dla danych operacyjnych, ale przygotowanie i kontrola informacji — atrybuty, powiązania, kompletność, zatwierdzenie do publikacji — odbywa się w PIM, a zakres tych funkcji zależy od wybranego rozwiązania i jego konfiguracji (Tandemite).

Drugi to zasilanie wielu kanałów z jednego źródła: w Comarch e-Sale jedno konto integracji obsługuje jednocześnie zamówienia, stany magazynowe, oferty i ceny w Allegro. Sprawdź, czy API udostępnia eksport przyrostowy i filtrowanie po dacie modyfikacji, czy wymaga pobierania całych zbiorów — od tego zależy obciążenie łączonych systemów i częstotliwość synchronizacji.

Checklista: kto za co odpowiada przy integracji

Pytania do dostawcy zbierz przede wszystkim wokół odpowiedzialności, bo to najczęściej luka w dokumentacji technicznej. Kto jest administratorem, a kto procesorem danych w projektowanej integracji i co zapisano w umowie powierzenia (Synergius CRM)?

Kto konfiguruje uprawnienia i role? W modelu chmurowym infrastruktura należy do dostawcy, ale firmie pozostaje ustalanie uprawnień i decydowanie o wykorzystaniu danych (Livespace). Musi być jasne, po czyjej stronie leży bieżące utrzymanie tych ustawień.

Kto utrzymuje elementy, których samo API nie zapewnia? Transport danych, kolejki komunikatów i ponawianie nieudanych operacji należą w opisanych architekturach do warstwy integracyjnej, a nie do ERP (Tandemite).

Uzupełnij to pytaniami o zmiany i testy po stronie dostawcy. Jak dostawca informuje o wygaszeniu interfejsu i jaki daje okres przejściowy, skoro starsze API może wyłączyć zewnętrzna platforma — jak Allegro WebAPI wyłączone od 13 stycznia 2020 roku (Comarch)?

Czy aktualizacje systemu są automatyczne i kto po nich powtarza testy integracji (Supremis, przy porównaniu modeli wdrożenia)? Czy udostępniane jest środowisko testowe z trybem testowym i czy testy można wykonać samodzielnie (Comarch)?

Kto odpowiada za szyfrowanie transmisji i kopie zapasowe w wybranym modelu wdrożenia (NMI ERP, Livespace)? I wreszcie: czy konto integracyjne ma własną, wąską rolę zamiast uprawnień administracyjnych oraz czy historia zmian pozwala odróżnić modyfikacje wykonane przez integrację od zmian wprowadzonych przez ludzi (NMI ERP, Livespace).

Checklista: kto za co odpowiada przy integracji