API Studio TCS.net - wymiana kartotek z innymi systemami
Studio TCS.net udostępnia interfejs API do wymiany kartotek z innymi systemami firmy oraz import kartotek z plików CSV i XLS. Gotowe są cztery operacje: założenie i aktualizacja kartoteki narzędzia oraz założenie i aktualizacja kartoteki kontrahenta. Gotowe operacje nie obejmują dokumentów magazynowych ani wypożyczeń, a pozycje API do systemu ERP w menu importu nie są integracjami. Strona jest przeznaczona dla programistów i administratorów, którzy przygotowują wymianę danych.
Menu Import kartotek ma trzy karty. Karty Import z pliku csv i Import z pliku xls mają po trzy pozycje: Import kartotek magazynowych, Import kontrahentów i Import pracowników. Trzecia karta, API do systemu ERP, ma dziewięć pozycji z nazwami systemów ERP. Żadna z nich nie uruchamia synchronizacji, bo wszystkie otwierają ten sam ekran z napisem Brak dostępu. Kafelki nie zastępują więc konektorów, których program nie zawiera.
Na tej stronie
Po wybraniu kafelka z karty API do systemu ERP w obszarze roboczym pojawia się biała karta z napisem Brak dostępu i pustym paskiem pod nim. Karta nie ma pól ani przycisków. W menu bocznym rozwinięta jest sekcja KARTOTEKI, a aktywna pozycja to Import kartotek. Ten sam ekran otwiera każdy z dziewięciu kafelków, więc nazwa systemu na kafelku nie oznacza gotowej integracji.
Cztery operacje API
Operacje dotyczą wyłącznie kartotek. Każdą wywołuje system zewnętrzny, a program wykonuje zdefiniowaną dla niej logikę w bazie danych.
| Operacja | Obiekt | Skutek |
|---|---|---|
| Założenie kartoteki narzędzia | Kartoteka asortymentowa, opisana na stronie o kartotekach magazynowych | Nowa kartoteka w programie. |
| Aktualizacja kartoteki narzędzia | Kartoteka asortymentowa | Zmiana danych istniejącej kartoteki. |
| Założenie kartoteki kontrahenta | Kontrahent, także pracownik (kontrahenci i pracownicy to osobne rejestry) | Nowa kartoteka w programie. |
| Aktualizacja kartoteki kontrahenta | Kontrahent, także pracownik | Zmiana danych istniejącej kartoteki. |
System zewnętrzny, w którym prowadzi się pracowników albo asortyment, może zasilać kartoteki Studio TCS.net zamiast ręcznego dopisywania. Zakres przekazywanych pól uzgadnia się przed wdrożeniem.
Jak wygląda wywołanie
Wywołanie ma stały kształt niezależnie od operacji. Tabela zbiera elementy, które musi uwzględnić system zewnętrzny.
| Element | Opis |
|---|---|
| Metoda | Żądanie POST z treścią w formacie JSON. |
| Odpowiedź | Treść w formacie JSON. Wynik operacji znajduje się w treści odpowiedzi. |
| Kod 200 | Operację wykonano. Wynik biznesowy, także błąd logiki, jest w treści odpowiedzi. |
| Kod 400 | Nieprawidłowe dane żądania. |
| Kod 401 | Nieprawidłowe dane uwierzytelniające. |
| Konto | Wywołanie wymaga osobnego konta technicznego, a nie konta użytkownika. |
| Baza danych | Poziom zgodności bazy co najmniej 130, czyli SQL Server 2016 lub nowszy. Wymaga go cały program, także funkcje przetwarzające dane w formacie JSON. |
Kod 200 nie oznacza sukcesu. Program zwraca ten kod także wtedy, gdy logika operacji odrzuciła dane, a przyczynę podaje treść odpowiedzi. System zewnętrzny musi więc czytać treść i obsługiwać ją osobno od kodów 400 i 401.
Logika leży w bazie. Nowa operacja nie wymaga zmiany interfejsu, bo dopisuje się ją po stronie bazy danych. Zmiana reguły nie zmusza wtedy do przebudowy systemu zewnętrznego, o ile struktura danych zostaje ta sama. Adresów usług i nazw pól nie publikujemy w instrukcji; przekazuje je zespół SoftwareStudio po uzgodnieniu zakresu. Silnik bazy, w którym leży ta logika, opisuje dokumentacja SQL Server w Microsoft Learn.
Przygotowanie integracji
- Uzgodnij z zespołem SoftwareStudio zakres operacji i struktury danych, zanim zaczną się prace. Zapytanie wyślij przez formularz kontaktowy.
- Sprawdź poziom zgodności bazy danych. Musi wynosić co najmniej 130.
- Ustal z administratorem programu osobne konto techniczne dla wywołań API.
- Przetestuj operacje na bazie testowej, a dopiero potem na produkcyjnej.
- Rejestruj po stronie systemu zewnętrznego każde wywołanie z kodem odpowiedzi. Błędy 400 i 401 obsłuż osobno od błędów logiki zwracanych w odpowiedzi 200.
Import z plików jako druga droga
Pozycje z kart Import z pliku csv i Import z pliku xls otwierają ekran importu, który prowadzi przez wybór rodzaju danych, plik z danymi i dwa przyciski: Audyt danych oraz Importuj dane. Panel Wzorcowy plik udostępnia arkusz z nagłówkami kolumn i arkusz Instrukcja z opisem wymagalności pól, a lista Kolumny w pliku oznacza kolumny wymagane i opcjonalne. Dla schematów tekstowych program udostępnia wzorzec w pliku tekstowym (CSV, TXT lub DAT) z separatorem wynikającym ze schematu, a ogólne zasady formatu CSV opisuje specyfikacja RFC 4180. Import omawia strona o imporcie kartotek, a szerszy opis wczytywania danych z Excela zawiera artykuł o imporcie danych z Excela do narzędziowni.
| Kryterium | Import z pliku | API |
|---|---|---|
| Kto uruchamia | Użytkownik w menu Import kartotek. | System zewnętrzny, bez udziału użytkownika. |
| Zakres | Trzy schematy: kartoteki magazynowe; kontrahenci; pracownicy. | Kartoteki narzędzi i kontrahentów, w tym pracowników. |
| Format | Plik XLS albo CSV według wzorca schematu. | Treść w formacie JSON. |
| Kontrola przed zapisem | Przycisk Audyt danych sprawdza plik bez zapisu. | Wynik operacji w treści odpowiedzi. |
| Kiedy pasuje | Jednorazowe wczytanie albo okresowe uzupełnienie kartotek. | Stała wymiana z innym systemem firmy. |
- Wzorcowy plik - przycisk Pobierz wzorcowy plik daje arkusz Dane z nagłówkami i arkusz Instrukcja z opisem wymagalności i typu pól.
- Audyt danych - sprawdza plik bez zapisu: brakujące kolumny wymagane, kolumny spoza schematu, puste pola wymagane i zgodność typów. Nie sprawdza powtórzeń.
- Importuj dane - zapisuje plik, a wynik pokazuje liczby Dane zapisane i Dane odrzucone oraz tabelę odrzuconych rekordów.
- Limit rekordów - wynika ze schematu. Po jego przekroczeniu import przerywa się w całości, a komunikat podaje limit i liczbę rekordów w pliku.
Czego integracja nie obejmuje
| Potrzeba | Czy gotowe | Jak ją zrealizować |
|---|---|---|
| Kartoteki narzędzi i kontrahentów | Tak, cztery operacje API i import z plików. | Według sekcji powyżej. |
| Dokumenty NW, NP, PW i RW | Nie. | Dopisanie operacji po stronie bazy we wdrożeniu. |
| Stany magazynowe i wypożyczenia | Nie. | Dopisanie operacji po stronie bazy we wdrożeniu. |
| Konektor do systemu ERP | Nie. Kafelki w menu importu otwierają ekran z napisem Brak dostępu. | Import plików albo osobny projekt integracyjny. Granice programu opisuje strona o programie. |
Ćwiczenie w demo - lekcja lub zajęcia
Ćwiczenie: ustal, które dane kartotek można wymienić z innym systemem i którą drogą
Uczeń ocenia możliwości wymiany danych tak, jak robi to analityk przed projektem integracji. Niczego nie wczytuje i nie zapisuje, bo konto demo jest wspólne dla wszystkich testujących. Rola w demo: Narzędziownia. Czas: około 15 minut.
- Uruchom bezpłatne demo Studio TCS.net w roli Narzędziownia i otwórz KARTOTEKI, Import kartotek. Zapisz nazwy grup pozycji.
- Wybierz Import z pliku xls, a w nim Import kartotek magazynowych. Odczytaj listę Kolumny w pliku i zapisz, które kolumny są wymagane, a które opcjonalne. Nie wczytuj żadnego pliku.
- Sprawdź, czy ekran ma panel Wzorcowy plik oraz przyciski Audyt danych i Importuj dane.
- Wróć do menu Import kartotek, otwórz jeden kafelek z grupy API do systemu ERP i przepisz napis widoczny na ekranie.
- Zapisz w dwóch zdaniach, czym wymiana przez API różni się od importu z pliku.
Pytanie kontrolne. Dlaczego kafelek z nazwą systemu ERP nie oznacza gotowej integracji i jak przenieść kartoteki narzędzi z zewnętrznego systemu do Studio TCS.net?
Podstawa programowa. Ćwiczenie realizuje efekt "stosuje systemy informatyczne w procesie magazynowania" z kwalifikacji SPL.01 Obsługa magazynów (jednostka SPL.01.5), w tym kryterium "opisuje systemy informatyczne stosowane w procesie magazynowania", w zawodzie technik logistyk. Pozostałe ćwiczenia zebraliśmy na stronie demo TCS.net na zajęciach.
Najczęstsze pytania
Czy API obsługuje dokumenty magazynowe i wypożyczenia?
Nie. Gotowe są cztery operacje na kartotekach narzędzi i kontrahentów. Kolejne operacje dopisuje się we wdrożeniu, po stronie bazy danych.
Czy mogę połączyć Studio TCS.net z SAP albo z Comarch?
Program nie ma gotowych konektorów do systemów ERP. Kafelki z nazwami SAP, Comarch, enova i innych systemów w menu importu otwierają tylko ekran z napisem Brak dostępu. Kartoteki wczytasz z plików CSV i XLS albo przez cztery operacje API.
Co oznacza kod 200 w odpowiedzi API?
Operację wykonano, ale nie zawsze z powodzeniem. Wynik biznesowy, w tym ewentualny błąd logiki, znajduje się w treści odpowiedzi, dlatego trzeba ją zawsze odczytać.
Gdzie znajdę adresy usług i strukturę żądań?
Nie publikujemy ich w instrukcji. Dotyczą bezpieczeństwa instalacji, więc przekazuje je zespół SoftwareStudio po uzgodnieniu zakresu integracji.
Który sposób wybrać: API czy import z pliku?
Import z pliku pasuje do jednorazowego wczytania albo okresowego uzupełnienia kartotek przez człowieka, z kontrolą w Audycie danych. API pasuje do stałej wymiany, którą uruchamia system zewnętrzny.
Jakiej wersji SQL Server wymaga API?
Program wymaga poziomu zgodności bazy co najmniej 130, czyli SQL Server 2016 lub nowszego. Od tego poziomu baza obsługuje funkcje JSON, których używa program.
Słownik pojęć
- API
- Interfejs, przez który system zewnętrzny wywołuje operacje programu. W Studio TCS.net gotowe są cztery operacje na kartotekach.
- JSON
- Format tekstowy, w którym przekazuje się żądanie i odpowiedź. Wynik operacji zawsze czyta się z treści odpowiedzi.
- Konto techniczne
- Osobne konto przeznaczone do wywołań API, inne niż konta użytkowników pracujących w menu.
- Poziom zgodności bazy
- Ustawienie bazy SQL Server. Wartość 130 lub wyższa umożliwia przetwarzanie danych JSON.
- Audyt danych
- Sprawdzenie pliku importu bez zapisu: kolumn, pól wymaganych oraz typów danych.
- Wzorcowy plik
- Plik XLSX z arkuszem Dane i arkuszem Instrukcja, który pobiera się z ekranu importu i wypełnia własnymi danymi.