Systim API

Czym jest API?

API (Application Programming Interface ) to interfejs pozwalający na komunikację pomiędzy różnymi programami. Obrazowo można powiedzieć, że jest to "gniazdko", w które mogą się wpiąć "wtyczki" innych programów, by pobierać różne informacje z Systim oraz te dane wysyłać. Taka "wtyczka" musi zostać najpierw przygotowana przez programistów. Nazywamy to "integracją" dwóch programów.

Poniższy podręcznik obsługi API jest podręcznikiem przeznaczonym dla programistów. Jeśli nie jesteś programistą, to najlepiej podesłać adres tej strony do producenta programu, który chcesz z Systim zintegrować, bądź do znajomego programisty.


Jak połączyć się z API?

Z API korzystamy łącząc się poprzez zapytanie POST lub GET z adresem: https://KONTO.systim.pl/jsonAPI.php

Dostępne jest zarówno połączenie https jak i http. Z przyczyn bezpieczeństwa zalecane jest korzystanie z połączenia https. W testach połączenie http wykazuje większą szybkość, co spowodowane jest sposobem działania połączeń szyfrowanych. Jeśli nasza firma, a co za tym idzie konto, nazywa się "abcd", to łączymy się adresem: https://abcd.systim.pl/jsonAPI.php

Jako parametry podajemy nazwę wywoływanej metody, login, wygenerowane hasło do API (zmienna pass) oraz dodatkowe parametry. Aby przykładowo utworzyć nową firmę poprzez API należy wywołać następujący adres:

https://abcd.systim.pl/jsonAPI.php?act=addCompany&login=admin&pass=c45lcd45&nip=586-212-09-28&nazwa_skrot=Enadis&nazwa=Enadis Sp. z o.o.&miejscowosc=Gdynia&ulica=al. Zwycięstwa 96/98&kod=81-451

Hasło do API należy wygenerować w zakładce użytkownicy, natomiast login to nazwa użytkownika dla którego wygenerowaliśmy klucz:

klucz api

Wywołanie można wykonać następująco:
1. Poprzez wklejenie linku do przeglądarki - przydatne do celów testowych. Nie zalecane w środowiskach produkcyjnych ze względu na specyficzny sposób kodowania niektórych znaków przez przeglądarki internetowe.
2. Poprzez dowolny język programowania, np. w przypadku PHP:
- przy użyciu funkcji file_get_contents()
- przy użyciu biblioteki CURL

Należy pamiętać, aby wszystkie zmienne (a przynajmniej te, które zawierają znaki niedozwolone do użycia w adresach url) uprzednio zakodować funkcją urlencode();

Przykładowe wywołanie może więc wyglądać tak:

					 $c = curl_init();
					 curl_setopt($c, CURLOPT_URL, 'https://abcd.systim.pl/jsonAPI.php');
					 curl_setopt($c, CURLOPT_POST, true); //sposób przesyłania - (true metoda POST)
					 curl_setopt($c, CURLOPT_POSTFIELDS, 'act=addCompany'.
								'&login=admin'.
								'&pass=' . urlencode('45lcd45') .
								'&nip=' . urlencode('586-212-09-28').
								'&nazwa_skrot=' . urlencode('Enadis').
								'&nazwa=' . urlencode('Enadis Sp. z o.o.').
								'&miejscowosc=' . urlencode('Gdynia').
								'&ulica=' . urlencode('al. Zwycięstwa 96/98').
								'&kod=' . urlencode('81-451')); //dane do wysłania
					 curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
					 $wynik = curl_exec($c);
					 curl_close($c);
					

Po wywołaniu otrzymujemy rezultat w zmiennej $wynik, która jest zakodowaną w formacie JSON grupą obiektów. Aby skonwertować ją do postaci tablicy (parametr true oznacza, że otrzymane obiekty są konwertowane do tablicy asocjacyjnej):

						$dane = json_decode($wynik,true);
					

Jeśli metoda została wykonana prawidłowo, to zmienna $dane['error']['code'] będzie równa 0 (zero).

Jeśli metoda została wykonana nieprawidłowo, to zmienna$dane['error']['code'] będzie większa od zera (kolejne numery wskazują na rodzaj błędu). Zmienna $dane['error']['message'] będzie zawierać komunikat błędu, zaś zmienna $dane['error']['fields'] będzie zawierała listę pól (parametrów), które zostały błędnie wypełnione, w postaci tablicy asocjacyjnej. Przykłady weryfikacji zwracanych danych znajdują sie poniżej oraz w opisach poszczególnych metod.

					if($dane['error']['code']==0) echo "OK!";
					else
					{
						echo "Wystąpił błąd nr " . $dane['error']['code'] . ": " . $dane['error']['message'] . "
" . "Następujące pola zostały wypełnione błędnie: " . implode(', ', $dane['error']['fields']) . "."; }

Kody błędów:


- nr błędu: 1, komunikat: Nieprawidłowa domena.

Błąd ten oznacza, że podany adres do API nie jest poprawny. Przykładowy poprawny adres: http://abcd.systim.pl gdzie abcd jest przykładową nazwą konta.

- nr błędu: 2, komunikat: Dostęp zabroniony.

Błąd ten występuje w przypadku gdy dla danego konta Systim zostały ustawione adresy dostępu IP, a IP z którego następuje próba połączenia z API jest różne od przyznanej puli. Może również wystąpić w przypadku gdy dane konto Systim zużywa zbyt dużo zasobów serwera poprzez ciągłą komunikację z API i API zostanie z tego powodu zablokowane.

- nr błędu: 3, komunikat: Nie podano loginu i/lub hasła.

Błąd występuje w przypadku gdy nie zostanie podany login bądź hasło do API.

- nr błędu: 4, komunikat: Nieprawidłowy login i/lub hasło.

Błąd ten występuje w przypadku gdy podane hasło lub login jest niepoprawne.

- nr błędu: 5, komunikat: Nie wybrano metody.

Błąd występuje gdy nie została podana metoda lub podana metoda została wprowadzona błędnie (parametr "act").

- nr błędu: 6, komunikat: Nie wypełniono poprawnie wymaganych pól.

Podane pola obowiązkowe zostały wypełnione błędnie lub są puste. Może również wystąpić gdy podano identyfikator zasobu, który nie istnieje, np. gdy podamy parametr "id_kontrahenta" jako 95, ale w bazie danych brak kontrahenta o takim numerze ID.

- nr błędu: 7, komunikat: Błąd zapisu do bazy.

Błąd bazy danych oznaczający, że próba zapisu danych do bazy nie powiodła się (błąd bazy danych, lub połącznia z bazą danych).

- nr błędu: 8, komunikat: Brak danych.

Błąd ten występuje w przypadku gdy następuje próba pobrania danych i zwrócony wynik wyszukiwania jest pusty (np. brak kontrahentów w bazie danych), lub gdy zasób o podanym numerze ID nie istnieje (np. brak kontrahenta o podanym ID).

- nr błędu: 9, przykładowy komunikat: Nie można usunąć kategorii zawierającej podkategorie.

Błąd pojawiający się w przypadku gdy nie można usunąć danego zasobu (np. kontrahenta, kategorii), ze względu na to, iż usunięcie jest z jakiegoś powodu blokowane. Przykładowo nie można usunąć kategorii nadrzędnej, która zawiera w sobie inne podkategorie. Nie można również np. usunąć produktu, który został użyty w fakturach, dokumentach magazynowych lub zamówieniach.

- nr błędu: 10, przykładowy komunikat: Ta wersja programu nie pozwala na wprowadzanie paragonów fiskalnych.

Obecna wersja programu nie pozwala na wykonanie danej operacji (np. nie wykupiono dostępu do jednej z funkcji programu, którego dotyczy metoda API.)

- nr błędu: 11, przykładowy komunikat: Ten dokument nie może zostać skorygowany.

Błąd ten występuje w przypadku gdy następuje próba stworzenia korekty dokumentu, który nie może zostać skorygowany (np. paragonu fiskalnego, czy faktury Pro Forma)

W przypadku pobierania danych należy pamiętać, że w związku z ograniczeniami bazy danych wartości "null" dla zmiennych typu "string" mogą być zwracane jako pusty string. Dla zmiennych liczbowych zwracane są jako wartość null lub również jako pusty string.

Stringi zwracane przez API są zakodowane funkcją htmlspecialchars(), która zamienia niektóre znaki na odpowiednie encje. Jeśli będziemy po pobraniu danych z API wyświetlać w przeglądarce internetowej to najlepiej zachować taki format. Jeśli jednak chcemy dane przesyłać do innych programów, czy np. do innych plików tekstowych, to powinniśmy otrzymane ciągi znaków zdekodować funkcją htmlspecialchars_decode().

Dane wysyłane do API nie powinny być zakodowane funkcją htmlspecialchars(). API automatycznie zakoduje wszystkie przesyłane łańcuchy znaków tą funkcją. Dane liczbowe są wysyłane i zwracane z kropką jako separatorem części dziesiętnej. Wartości typu boolean mogą być zwracane jako wartość 0 lub 1.

API pracuje wyłącznie w trybie UTF-8.

Dane wysyłane przez API są przez program konwertowane - usuwane są z nich wszelkie tagi HTML, znaki specjalne (funkcja htmlspecialchars()), oraz ich zawartość jest obcinana z dodatkowych spacji przy użyciu funkcji trim().

UWAGA! API nie podlega uprawnieniom, to znaczy że wykonując operacje przez API posiadamy wszystkie uprawnienia, możemy zarówno dodawać, usuwać, edytować jak i przeglądać wszystkie elementy.

Metody dostępne w API

Listy

listCurrencies - lista walut

listPriceGroups - lista grup cenowych

listRegions - lista województw

listUECountries - lista krajów Unii Europejskiej

listDeliveryTypes - lista sposobów dostawy

listCustomers - lista kontrahentów

Zarządzanie produktami

addProduct - dodanie produktu

delProduct - usunięcie produktu

updProduct - edycja produktu

getProduct - pobranie informacji o danym produkcie

getAttachment - pobranie załącznika dla danego produktu

listProducts - lista produktów

listPQuantities - ilość produktów w magazynie

changePQuantity - zmiana ilości produktu w magazynie

Zarządzanie kategoriami

addCategory - dodanie kategorii

delCategory - usunięcie kategorii

updCategory - edycja kategorii

getCategory - pobranie informacji o danej kategorii

listCategories - lista kategorii

Zarządzanie parametrami produktów

addAttribute - dodanie nowego parametru

delAttribute - usuwanie istniejącego parametru

updAttribute - edycja istniejącego parametru

getAttribute - pobranie informacji o danym parametrze

listAttributes - lista parametrów

Zarządzanie kontrahentami

addCompany - dodanie nowego kontrahenta

delCompany - usuwanie istniejącego kontrahenta

updCompany - edycja nowego kontrahenta

getCompany - pobranie informacji o kontrahencie

listCompanies - lista kontrahentów

Zarządzanie zamówieniami

addOrder - dodanie nowego zamówienia

delOrder - usunięcie istniejącego zamówienia

updOrder - edycja istniejącego zamówienia

getOrder - wyświetlenie informacji dla istniejącego zamówienia

getOrderPDF - pobranie pliku PDF dla zamówienia

listOrders - lista zamówień

changeOrderStatus - zmiana statusu zamówienia

listOrderStatus - pobranie listy możliwych statusów zamówienia

Zarządzanie fakturami

addInvoice - dodanie nowej faktury

delInvoice - usunięcie istniejącej faktury

updInvoice - edycja istniejącej faktury

getInvoicePDF - pobranie PDF istniejącej faktury

listInvoices - lista faktur

addInvoiceCorrect - dodanie korekty faktury

Zarządzanie dokumentami magazynowymi

addStoreDocument - dodanie nowego dokumentu magazynowego

getStoreDocumentPDF - pobranie dokumentu do PDF

listStoreDocuments - lista dokumentów magazynowych

Zarządzanie płatnościami

addPayment - dodanie nowej płatnośći, z możliwością powiązania jej z dokumentem

delPayment - usuwanie jednej lub wielu płatności

Wykorzystujemy pliki "cookies" aby nasz serwis lepiej spełniał Państwa oczekiwania. Możesz zablokować możliwość wykorzystywania tych plików poprzez zmianę ustawień w swojej przeglądarce internetowej. ok