Systim — obsługa, integracje

Systim API pozwala innym programom pobierać dane z Systim i przesyłać je do programu po przygotowaniu integracji.¹
Ten poradnik pokazuje, jak uzyskać dostęp, dobrać metody API i rozpoznać błędy. Wyjaśnia też, na co zwrócić uwagę po aktualizacji programu. W wykazie dokumentacji Systim znajduje się 92 metod API.²

Czym jest API Systim i do czego służy?

Systim API to interfejs programistyczny do automatyzacji pracy z danymi programu. Obejmuje trzy obszary: dane handlowe, magazynowe i księgowe.
Integrację można więc zaplanować wokół zadań firmy. Dane nie muszą wtedy trafiać między programami przez ręczne przepisywanie.

Jakie dane i funkcje Systim można obsługiwać przez API?

API Systim udostępnia metody obsługi produktów, stanów magazynowych, kategorii, parametrów produktów i kontrahentów.¹ Obsługuje też zamówienia, faktury sprzedażowe i zakupowe, dokumenty magazynowe oraz płatności.¹
Sklep internetowy można połączyć z Systim przez API. Dostępne są również wtyczki do popularnych programów obsługujących sklepy.³ Strona integracji wymienia trzy platformy z gotowymi integracjami: Shoper, PrestaShop i WooCommerce. Wtyczki tworzą osoby trzecie.⁴

API Systim pozwala generować pliki JPK_FA (faktur), JPK_KR (ksiąg rachunkowych), JPK_PKPiR (podatkowej księgi przychodów i rozchodów) oraz JPK_VAT (ewidencji VAT). Obsługuje również księgowania KPiR, KH (ksiąg handlowych) i ryczałtu.¹
Można w nim wygenerować zestawienie podatkowe, bilans oraz rachunek zysków i strat.¹ Dokumentacja API opisuje generowanie czterech struktur JPK: FA, KR, PKPiR i VAT.⁵

Jak nawiązać połączenie z API?

API Systim przyjmuje żądania POST i GET.¹ Połączenie działa przez HTTP oraz HTTPS. Systim zaleca HTTPS ze względów bezpieczeństwa.¹

• Adres API Systim ma postać https://KONTO.systim.pl/jsonAPI. Człon KONTO oznacza konto używane w adresie usługi.
• Żądanie do API Systim kieruje się na ten adres wybraną metodą. Trzeba w nim przekazać parametry wymagane przez wywoływaną metodę.
• Odpowiedź API Systim zawiera grupę obiektów zapisanych w formacie JSON, służącym do wymiany danych.¹

Po wysłaniu żądania wynik można odczytać z ustrukturyzowanej odpowiedzi. Dokumentacja opisuje jeden format odpowiedzi API: JSON.²

Jak uzyskać i skonfigurować dostęp do API Systim?

Dostęp do API Systim wymaga tokena. Uzyskuje się go metodą login z parametrami login i pass.¹ Hasło do API generuje się w zakładce użytkowników dla wybranego użytkownika.¹
Token pozostaje ważny przez czas ustawiony w opcjach programu dla automatycznego wylogowania. Dokumentacja nie podaje stałej liczby minut.²

• Logowanie do API Systim polega na użyciu wygenerowanego hasła przy wywołaniu metody login.
• Token API Systim należy przekazywać w kolejnych wywołaniach w parametrze token.¹
• Ważność tokena API Systim zależy od ustawionego czasu automatycznego wylogowania. Po wygaśnięciu trzeba uzyskać nowy token.¹ Poprawne logowanie przez API odświeża czas jego wygaśnięcia.^1,2

Logowanie przez stronę WWW Systim usuwa sesje użytkownika wykorzystywane przez API. Uzyskanie tokena przez API nie usuwa tych sesji.¹
Operacje przez API nie podlegają uprawnieniom użytkownika: pozwalają dodawać, usuwać, edytować i przeglądać wszystkie elementy.¹ Kod integracji trzeba więc przygotować z uwzględnieniem zakresu tych operacji i ochrony danych dostępowych.²

Jak sprawdzić, czy połączenie z API działa?

Połączenie z API Systim sprawdza się przez wysłanie żądania i odczytanie pola error.code w odpowiedzi. Tabela zestawia jego wartości z wynikiem wykonania metody.
Pomyślne wykonanie oznacza wartość 0 w polu error.code.²

Pole error.code sygnalizuje prawidłowe wykonanie wartością 0, a błąd wartością większą od zera.¹
Samo nawiązanie połączenia nie wystarczy. Trzeba jeszcze odczytać wynik zwrócony przez metodę. Kod 13 oznacza brak sesji użytkownika, gdy przesłany token jest błędny lub nieaktualny.²

Metody API Systim w codziennej pracy

API Systim grupuje metody według zadań: obsługi kontrahentów, produktów, dokumentów handlowych i księgowości. Nazwa metody wskazuje operację, którą wykona integracja.
Przy planowaniu przepływu danych warto oddzielić pobieranie list od dodawania dokumentów i zmian w magazynie. W wykazie znajduje się 24 metod o nazwach zaczynających się od „list”. Służą do pobierania list lub zestawień.²

Jakie metody są dostępne w API Systim?

Metody API Systim dobiera się do danych i czynności, którą ma wykonać integracja. Poniższa lista porządkuje je według zastosowania.
W sekcji zarządzania produktami dokumentacja wymienia dziewięć metod. Obejmują między innymi dodawanie, edycję i pobieranie danych.²

• Metoda addCompany dodaje kontrahenta, a listCompanies pobiera listę kontrahentów.
• Metoda addProduct dodaje produkt, listProducts pobiera listę produktów, a changePQuantity zmienia ilość produktu.
• Metoda addOrder dodaje zamówienie. addSellInvoice dodaje fakturę sprzedaży, addPurchInvoice fakturę zakupu, a uploadDocument przesyła dokument.
• Metody generateJPK_FA i generateJPK_VAT generują odpowiednie pliki JPK. addKPiR dodaje wpis do księgi przychodów i rozchodów.

Integracja z API Systim powinna wybierać metodę według czynności wykonywanej na danych, nie tylko rodzaju dokumentu. Synchronizacja katalogu produktów wymaga innych metod niż tworzenie faktur lub zapisów księgowych.
Dokumentacja wymienia dziewięć metod w grupie produktów oraz 18 w grupach faktur sprzedażowych i zakupowych łącznie.²

Integracja z API Systim: diagnozowanie błędów

Błędy API Systim diagnozuj na podstawie odpowiedzi i danych wysłanych w żądaniu. Sam adres nie pokaże, co poszło nie tak. Dokumentacja odradza testowanie produkcyjnego API przez wklejenie adresu do przeglądarki, ponieważ przeglądarki kodują znaki w adresie.¹
W przykładzie Systim parametr adresu „96/98” zawiera ukośnik „/”. Po użyciu zalecanej funkcji urlencode() znak ten przyjmuje postać „%2F”.²

Jak rozpoznać i rozwiązać typowe błędy API Systim?

Błędy API Systim rozpoznawaj po komunikacie oraz parametrach i wartościach zwróconych w odpowiedzi. Kod błędu 6 oznacza puste lub niepoprawnie wypełnione pola wymagane. Może też wskazywać nieistniejący identyfikator zasobu.²

• Komunikat błędu API Systim odczytaj z pola error.message. Parametry wymagające poprawy znajdziesz na liście error.fields.^1,2
• Znaki niedozwolone w adresie URL zakoduj funkcją urlencode() przed wysłaniem zmiennych do API Systim.¹
• Danych wysyłanych do API Systim nie koduj funkcją htmlspecialchars(). Interfejs automatycznie koduje przesyłane ciągi znaków.¹
• Ciągi znaków zwrócone przez API Systim odkoduj funkcją htmlspecialchars_decode() przed przekazaniem ich do innego programu lub pliku tekstowego. Tak zaleca dokumentacja.¹
• Pola o wartości null obsłuż zależnie od typu danych. API Systim może zwrócić pusty ciąg dla pola tekstowego, a null lub pusty ciąg dla pola liczbowego.¹
• Dane liczbowe API Systim odczytuj z kropką jako separatorem dziesiętnym. Zwrócone wartości logiczne mają postać 0 lub 1.¹
• Zmiany w przesłanym tekście porównaj z regułami przetwarzania Systim. Program usuwa tagi HTML, koduje znaki specjalne i obcina dodatkowe spacje funkcją trim().¹

Diagnoza integracji Systim sprowadza się do poprawienia wskazanych parametrów oraz właściwego kodowania i odczytu danych.²

Aktualizacje programu a działanie integracji

Aktualizacje Systim wymagają kontroli integracji, bo jej kod korzysta z określonej struktury żądań i odpowiedzi API. Sprawdź odczyt danych, zapis na danych testowych oraz interpretację błędnej odpowiedzi.
Wynik każdej próby porównaj z zachowaniem, którego oczekuje program połączony z Systim.

Problem po aktualizacji wymaga ustalenia, czy dotyczy połączenia, danych wejściowych czy przetwarzania odpowiedzi przez integrację.
Taki podział pozwala wskazać miejsce wymagające poprawki. Nie każdy błąd wynika z aktualizacji programu.²