W skrócie
Opisy wcześniejszych wdrożeń Studio RMA.net wymieniają WebAPI REST z danymi w JSON albo XML i klucze API, ale dokumentacja nie opisuje punktów końcowych ani formatu komunikatów. Integrację z systemem WMS potwierdza referencja operatora logistycznego z 2012 roku, w której zleceniodawca uczestniczył w procesie przez stronę WWW. Gdy usługi sieciowe nie są potrzebne, dane przechodzą przez wymianę plikową: import kartotek i eksport reklamacji z usługami. Zakres API ustalamy w analizie przedwdrożeniowej razem z zasadami kluczy i uprawnień.
Co wiemy o API programu
Opisy wcześniejszych wdrożeń wymieniają moduł API programu i WebAPI REST, przez które program wymieniał dane z systemami ERP i WMS. Komunikaty miały postać JSON albo XML, a dostęp chroniły klucze API. W starszych wdrożeniach stosowaliśmy też usługi SOAP z opisem WSDL. Te opisy dotyczą konkretnych wdrożeń, więc nie przesądzają, jakie dane API udostępni w nowej integracji. Dokumentacja nie opisuje jednak punktów końcowych API ani formatu komunikatów, więc zakres wymiany ustalamy w analizie przedwdrożeniowej.
Strona produktu wymienia integracje z systemami ERP, a referencja z 2012 roku potwierdza integrację z systemem WMS. Połączenie z konkretnymi systemami opisujemy przy reklamacjach w SAP i integracji reklamacji z enova365 i Microsoft Dynamics, a wszystkie sposoby wymiany przy integracji programu do reklamacji z ERP. API jest tylko jednym z tych sposobów i nie zawsze najtańszym. Przy małej liczbie spraw tańsza bywa wymiana plików albo formularz na stronie firmy.
Usługi sieciowe i pliki w wymianie danych
Usługi sieciowe przekazują dane między systemami na bieżąco, pojedynczymi komunikatami. WebAPI REST przesyła je żądaniami HTTP, najczęściej w formacie JSON, a SOAP opisuje usługę plikiem WSDL i przesyła komunikaty XML. Wymiana plików przenosi dane paczkami, w ustalonych odstępach czasu. Zestawiamy sposoby znane z wcześniejszych wdrożeń:
| Sposób | Format danych | Kiedy go wybieramy |
|---|---|---|
| WebAPI REST | JSON albo XML | System partnera ma usługi sieciowe i potrzebuje danych na bieżąco |
| SOAP z WSDL | XML | Starszy system partnera udostępnia tylko usługi SOAP |
| Replikacja baz | Kopia tabel bazy danych | Oba systemy działają na serwerach, między którymi można kopiować dane |
| Wymiana plików | Arkusze Excel | Wystarcza okresowa aktualizacja, np. kartotek towarów |
Wybór sposobu zależy od systemu po drugiej stronie, a nie od preferencji działu reklamacji. System z usługami REST przyjmie komunikat o reklamacji od razu, a system bez usług sieciowych tylko plik. Dlatego pierwsze pytanie w analizie dotyczy interfejsów, które partner już ma. Często łączymy dwa sposoby, np. kartoteki przez pliki, a statusy reklamacji przez usługi sieciowe.
Sposób wymiany wybieramy według interfejsów, które partner już ma, a często łączymy oba.
Klucze API i zabezpieczenie wymiany
Według opisów programu dostęp do API chronią klucze API, a komunikację program szyfruje protokołem SSL. Opisy różnią się co do miejsca przechowywania kluczy, więc przy wdrożeniu ustalamy je razem z ustawieniami opisanymi przy parametrach programu do reklamacji i pliku web.config. Klucz API działa jak hasło systemu partnera, dlatego stosujemy cztery zasady:
- Osobny klucz dla systemu - ERP i WMS dostają różne klucze, więc odcięcie jednego połączenia nie zatrzymuje drugiego.
- Tylko połączenie szyfrowane - klucz przekazujemy wyłącznie przez HTTPS, nigdy w treści zwykłego e-maila.
- Minimalne uprawnienia - klucz daje dostęp tylko do danych potrzebnych danemu systemowi.
- Wymiana klucza - nowy klucz po odejściu osoby, która znała stary, i po każdym podejrzeniu wycieku.
Zasady ochrony danych w programie opisujemy przy bezpieczeństwie danych w systemie reklamacyjnym. Dane reklamujących w komunikatach API są danymi osobowymi, więc partner dostaje tylko pola potrzebne do jego części procesu. System magazynowy potrzebuje numeru RMA i danych towaru, a nie adresu e-mail klienta. Zakres przekazywanych pól uzgadniamy z osobą odpowiedzialną za ochronę danych, np. z inspektorem ochrony danych, jeśli firma go wyznaczyła.
Integracja z systemem WMS
Referencja z 2012 roku dotyczy operatora logistycznego mrożonek, który połączył program z systemem WMS. Zleceniodawca, czyli właściciel towaru w magazynie operatora, uczestniczył w procesie reklamacyjnym przez stronę WWW. Według starszych opisów integracja z WMS przebiegała przez API.
W opisie dawnej integracji z systemem magazynowym Qguar program odczytywał na bieżąco dane o wysyłkach i zwrotach z bazy Oracle. Reklamacja w magazynie zewnętrznym dotyczy zwykle konkretnej dostawy, więc numer dostawy i partia towaru powinny przyjść z WMS, a nie od pracownika. Przy mrożonkach system magazynowy zna też datę przydatności partii, więc reklamacja może ją przejąć bez przepisywania. W relacjach między firmami numerem RMA oznacza się zwykle przesyłkę zwrotną, więc magazyn przypisuje zwrot do właściwej sprawy. Proces reklamacji u operatora logistycznego opisujemy przy reklamacjach w logistyce i magazynie zewnętrznym.
Wymiana plików bez usług sieciowych
Gdy system partnera nie ma usług sieciowych, program wymienia dane przez pliki. Ekran Excel w menu Kartoteki ze starszego interfejsu ma import kartotek magazynowych i kontrahentów - dostawców oraz eksport reklamacji i usług serwisowych. Wymiana plikowa nie działa w czasie rzeczywistym, ale nie wymaga połączenia między systemami. Import kartotek przydaje się też przy starcie programu, gdy trzeba jednorazowo przenieść towary i kontrahentów z ERP.
Eksport list reklamacji do pliku opisujemy przy eksporcie tabeli reklamacji do pliku. Plik do importu musi mieć ustalony układ kolumn, więc zmiana układu po stronie ERP wymaga zmiany importu. Dlatego układ pliku zapisujemy w dokumentacji wdrożenia razem z osobą odpowiedzialną za jego zmiany.
Moduł WWW dla partnerów zamiast API
Nie każdy partner potrzebuje API, zwłaszcza gdy zgłasza kilka reklamacji w miesiącu. Według starszych opisów firmy partnerskie, np. sieci sklepów, logują się do modułu WWW dla firm adresem e-mail i hasłem. Moduł służy m.in. do rejestracji reklamacji przez dystrybutora i sprawdzania statusu zgłoszenia.
Formularz na stronie firmy opisujemy przy formularzu reklamacyjnym online na stronie firmy. API opłaca się dopiero wtedy, gdy partner zgłasza tyle spraw, że ręczne wpisywanie w formularzu kosztuje go więcej niż integracja. Próg ustalamy z partnerem na podstawie liczby zgłoszeń z ostatnich miesięcy. Formularz nie wymaga też po stronie partnera żadnych prac informatycznych.
Specyfikacja integracji przez API
Integrację przez API opisujemy w specyfikacji, zanim powstanie pierwszy komunikat. Specyfikacja powstaje w analizie przedwdrożeniowej, którą opisujemy przy analizie przedwdrożeniowej systemu reklamacji. Specyfikację zatwierdzają obie strony, zanim zaczną się prace programistyczne. Obejmuje ona cztery ustalenia:
- Dane i kierunek - które pola przechodzą z programu do partnera, a które w drugą stronę.
- Częstotliwość - komunikat przy każdej zmianie albo paczka w ustalonych godzinach.
- Obsługa błędów - co dzieje się z komunikatem, gdy system partnera nie odpowiada, np. ponowienie wysyłki.
- Odpowiedzialność - kto po obu stronach pilnuje integracji i zmian w interfejsie.
Specyfikacja chroni obie strony przy zmianach, bo każda nowa wersja ERP albo WMS może zmienić interfejs. Zmianę porównujemy wtedy z ustaleniami ze specyfikacji, zamiast szukać przyczyny błędu w działającej integracji. Integracja bez specyfikacji działa do pierwszej aktualizacji systemu partnera.