Newsletter
Dołącz do naszych subskrybentów i otrzymuj najświeższe informacje na temat Systim.
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.
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
Aby otrzymać dostęp do metod API należy wpierw wygenerować token używając metody login z parametrami login oraz pass (wygenerowane hasło do API). Przykładowo, na koncie abcd, należy wywołać następujący adres:
https://abcd.systim.pl/jsonAPI.php?act=login&login=admin&pass=c45lcd45
Hasło do API należy wygenerować w zakładce użytkownicy, natomiast login to nazwa użytkownika dla którego wygenerowaliśmy klucz:
Token jest ważny tyle czasu na ile został ustawiony czas po którym następuje automatyczne wylogowanie z systemu w opcjach programu. Uzyskany token należy przekazywać w zapytaniach do API jako parametr o nazwie token. Aby przykładowo utworzyć nową firmę poprzez API należy wywołać następujący adres:
https://abcd.systim.pl/jsonAPI.php?act=addCompany&token=6aed003dc54951c043f8d1ad4b4804a2a8a40f&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
Każde poprawne zalogowanie się do API powoduje odświeżenie czasu wygaśnięcia tokena. W przypadku wygaśnięcia tokena należy go wygenerować poprzez ponowne wywołanie metody login w API. Zalogowanie się na konto Systim przez stronę WWW spowoduje usunięcie wszystkich sesji użytkownika wykorzystywanych przez API. Natomiast uzyskanie tokena przez API nie spowoduje usunięcia sesji użytkownika (zarówno tych wykorzystywanych przez API jak i tych wykorzystywanych przez stronę WWW).
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'.
'&token=6aed003dc54951c043f8d1ad4b4804a2a8a40f' .
'&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:
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.
Logowanielogin - logowanie, uzyskanie tokena dostępowego ListylistCurrencies - 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 listTaxOffices - lista urzędów skarbowych Zarządzanie produktamiaddProduct - 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 kategoriamiaddCategory - dodanie kategorii delCategory - usunięcie kategorii updCategory - edycja kategorii getCategory - pobranie informacji o danej kategorii listCategories - lista kategorii Zarządzanie parametrami produktówaddAttribute - dodanie nowego parametru delAttribute - usuwanie istniejącego parametru updAttribute - edycja istniejącego parametru getAttribute - pobranie informacji o danym parametrze listAttributes - lista parametrów Generowanie plików JPKgenerateJPK_FA - wygenerowanie JPK_FA generateJPK_KR - wygenerowanie JPK_KR generateJPK_PKPiR - wygenerowanie JPK_PKPiR generateJPK_VAT - wygenerowanie generateJPK_VAT Zarządzanie księgowościągenerateTaxInformation - wygenerowanie zestawienia podatkowego generateBalanceSheet - wygenerowanie bilansu generateProfitAndLossAccount - wygenerowanie rachunku zysków i strat listAccountingYears - lista lat księgowych |
Zarządzanie kontrahentamiaddCompany - dodanie nowego kontrahenta delCompany - usuwanie istniejącego kontrahenta updCompany - edycja nowego kontrahenta getCompany - pobranie informacji o kontrahencie listCompanies - lista kontrahentów Zarządzanie zamówieniamiaddOrder - 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 fakturamiaddSellInvoice - dodanie nowej faktury delSellInvoice - usunięcie istniejącej faktury updSellInvoice - edycja istniejącej faktury getSellInvoicePDF - pobranie PDF istniejącej faktury listSellInvoices - lista faktur addInvoice - dodanie nowej faktury (stara wersja) delInvoice - usunięcie istniejącej faktury (stara wersja) updInvoice - edycja istniejącej faktury (stara wersja) getInvoicePDF - pobranie PDF istniejącej faktury (stara wersja) listInvoices - lista faktur (stara wersja) getInvoice - pobranie danych faktury addInvoiceCorrect - dodanie korekty faktury Zarządzanie fakturami zakupowymiaddPurchInvoice - dodanie nowej faktury delPurchInvoice - usunięcie istniejącej faktury updPurchInvoice - edycja istniejącej faktury getPurchInvoicePDF - pobranie PDF istniejącej faktury listPurchInvoices - lista faktur getPurchInvoice - pobranie danych faktury Zarządzanie dokumentami magazynowymiaddStoreDocument - dodanie nowego dokumentu magazynowego getStoreDocumentPDF - pobranie dokumentu do PDF listStoreDocuments - lista dokumentów magazynowych getStoreDocument - Pobranie danych dokumentu przyjęcia/wydania Zarządzanie płatnościamiaddPayment - dodanie nowej płatnośći, z możliwością powiązania jej z dokumentem delPayment - usuwanie jednej lub wielu płatności |