= eDokumenty Api = System eDokumenty udostępnia API (Application Programming Interface) dzięki któremu jesteśmy w stanie przeprowadzać podstawowe czynności bez konieczności logowania do systemu. Usługa jest zabezpieczona rozszerzeniem WSSecurity protokołu SOAP i wymaga podania w nagłówkach wywołania XML nazwy użytkownika i hasła. Hasło i użytkownik to specjalne dane, które należy wprowadzić do pliku config.inc pod kluczami: {{{ #!php }}} Wartości stałych w powyższym przykładzie konfiguracji są tylko danymi prezentacyjnymi i nie powinno się ich używać na produkcyjnej bazie. Stałe te mogą mieć dowolne wartości ważne jednak aby te same wartości podać przy wywołaniu usługi SOAP w kliencie. '''Od wersji 4.0 systemu eDokumenty jest możliwość autentykacji poprzez dowolne konto użytkownika''' (nie musi to być EDOK_API_LOGIN, jak we wcześniejszych wersjach). Usługa jest dostępna pod adresem: {{{ http://{host}:{port}/eDokumentyApi.php }}} Wartość {host} oraz {port} należy zamienić odpowiednimi wartościami zgodnymi z konfiguracją serwera instalacyjnego systemu eDokumenty. Dodatkowo od wersji systemu 3.3 autentykacja nie wymaga nadpisania klienta Soap. Wystarczy do url z adresem serwisu dodać parametry GET w postaci {{{ #!php 'http://localhost/eDokumentyApi.php?a1='.EDOK_API_LOGIN.'&a2='.md5(md5(EDOK_API_PASSWORD).'_SOAP_eDok_api').'&a3='.DEFAULT_ENTITY_SYMBOL.'', "uri" => "eDokumentyAPI", 'encoding'=>'UTF-8' ); $client = new SoapClient(null, $ops); $params = array( 'name_1' => 'Daniel Wąsala' ); /* Invoke webservice method with your parameters, in this case: Function1 */ $response = $client->searchContacts($params); /* Print webservice response */ var_dump($response); }}} == Styl/format dokumentów SOAP == Api może działać w dwóch stylach/formatach: 1. RPC/encoded (domyślny). Adres usługi to !http://{host}/eDokumentyApi.php (!http://{host}/eDokumentyApi.php?wsdl) 2. Document/Literal. Adres usługi to !http://{host}/eDokumentyApi.php/2 (!http://{host}/eDokumentyApi.php/2?wsdl) == Uwagi dotyczące haseł == 1. Hasło powinno być zakodowane przy użyciu funkcji md5. {{{ $password = md5('haslo'); }}} 2. Jeżeli nie korzystamy z klasy '''EDokApiClient''', to doklejamy do zakodowanego hasła ciąg "_SOAP_eDok_api" i ponownie tworzymy skrót md5. {{{ $password = md5(md5('haslo').'_SOAP_eDok_api'); }}} == Obsługa błędów API == Zgodnie z przykładem dla PHP (pomijając całą otoczkę oraz brak parametrów) metoda do tworzenia dokumentu w przypadku błędy API lub wykonania kodu (parsowania klas etc) może zwrócić błędy z kodem do 100 lub powyżej. {{{ $doc_id = NULL; try { $doc_id = $client->createDocument(array()); var_dump($doc_id); } catch(SoapFault $fault) { var_dump($fault); if ($fault->faultcode < 100) { trigger_error("SOAP Fault: (faultcode: {$fault->faultcode}, faultstring: {$fault->faultstring})", E_USER_ERROR); } } Jak należy rozumieć ten kod: - poniżej 100 - błędy techniczne wykonania kodu, logiki kodu, parsowania (błędy w kodzie) etc - równe lub powyżej 100 - błędy walidacji API czyli wszystkie te błędy, które mogą pojawić się podczas sprawdzania parametrów lub braku logicznego powiązania pomiędzy nimi np. data rozpoczęcia jest większa niż zakończenia etc Błędy z kodem poniżej 100 powinny (jest zalecane) przerywać działanie aplikacji zewnętrznej gdyż wyraźnie wskazują na niepowodzenie wywołania usługi (techniczny błąd). Podobne zalecenie jest dla błędów >= 100. Obecnie mechanizm API zwraca błędy z kodami 100 lub 110, które wskazują na błąd parametrów a same kody błędów nie mają pomiędzy sobą większej różnicy - także dla obsługi błędów parametrów należy uwzględnić te dwa kody 100 oraz 110. }}} == Uwagi == '''Przekazywanie parametrów''' We wszystkich funkcjach w których parametr jest określony jako (array)$data możliwe jest przekazanie parametrów jako ciąg JSON (więcej na http://www.json.org/). Dzięki temu nie potrzeba tworzyć pseudo struktur tablic asocjacyjnych dla języków programowania, w których takich typów nie ma. '''Korzystanie z metod służących do wyszukiwania danych w kolumnach z datą np. searchContacts (od wersji 4.6.26, 4.7.2)''' W przypadku jeśli chcemy wyszukać obiekty w systemie np. klientów za pomocą metody searchContacts ale jako parametr wyszukiwania podajemy datę (format YYYY-MM-DD HH:MM lub YYYY-MM-DD) dodania (kolumna adddat) system umożliwia następujące sposoby wyszukiwania po dacie (wyszukuje klientów po kolumnie adddat): - 2014-12-12 10:10 - wszyscy klienci dodani w dacie 2014-12-12 10:10 (przedział czasu od 10:10 do 10:11 kolumna z datą jest rzutowana bez sekund) - 2014-12-12 - wszyscy klienci dodani w dacie 2014-12-12 (przedział wyszukiwania od 2014-12-12 00:00 do 2014-12-13 00:00) - 2014-12-12 10:10:: - wszyscy klienci dodani w dacie 2014-12-12 10:10 lub później (przedział wyszukiwania od 2014-12-12 10:10 do teraz) - 2014-12-12:: - wszyscy klienci dodani w dacie 2014-12-12 lub później (przedział wyszukiwania od 2014-12-12 00:00 do teraz) - 2014-12-12 10:10::2014-12-12 - wszyscy klienci dodani w dacie 2014-12-12 10:10 do 2014-12-12 (przedział wyszukiwania od 2014-12-12 10:10 do 2014-12-13 00:00) - ::2014-12-12 - wszyscy klienci dodani do 2014-12-12 (przedział wyszukiwania od początku świata do 2014-12-13 00:00) - ::2014-12-12 10:10 - wszyscy klienci dodani do 2014-12-12 10:10 (przedział wyszukiwania od początku świata do 2014-12-12 10:10) Na szczególną uwagę zasługuje modyfikator ::, który umożliwia definiowanie zakresów. Jeśli data wystąpi przed modyfikatorem wtedy jest uważana za początek zakresu. Jeśli po modyfikatorze wtedy za koniec zakresu. Jeśli, któraś z dat (przed lub za modyfikatorem) nie zostanie podana (a sam modyfikator będzie dostępny w parametrze) wtedy system automatycznie dostosuje się do żądania o zakres. W przypadku jeśli w parametrze data zostanie zdefiniowana bez godziny (YYYY-MM-DD) system automatycznie uzupełni godzinę według parametru i czy ma wyszukiwać po zakresie np. - 2014-12-12:: uzupełni 2014-12-12 00:00:: - czyli szukam od początku dnia 2014-12-12 - ::2014-12-12 uzupełni 2014-12-13::00:00 - czyli szukam do końca dnia 2014-12-12 (aby uwzględnić wszystkie wpisy do dnia następuje automatyczne powiększenie zakresu do początku dnia następnego) == Dokumentacja API 2.2.0 == Dokumentacja poszczególnych funkcji, parametrów oraz przykłady wywołań dostępne są poniżej: {{{ http://{host}:{port}/apps/edokumenty/classes/eDokumentyApi/DokumentacjaAPI.txt }}} ''' Dokumenty ''' * [wiki:DeployerGuide/Others/eDokumentyApi/CreateDocument Utwórz nowy dokument] * [wiki:DeployerGuide/Others/eDokumentyApi/UpdateDocument Aktualizacja dokumentu] * [wiki:DeployerGuide/Others/eDokumentyApi/GrantUserAccessToDocument Dodaj pracownika do uprawnionych w dokumencie] * [wiki:DeployerGuide/Others/eDokumentyApi/GrantGroupAccessToDocument Dodaj grupę do uprawnionych w dokumencie] * [wiki:DeployerGuide/Others/eDokumentyApi/AddAttachmentToDocument Dodaj załącznik do dokumentu] * [wiki:DeployerGuide/Others/eDokumentyApi/SetFileMetaText Ustawia meta text załącznika (używany przy wyszukiwaniu)] * [wiki:DeployerGuide/Others/eDokumentyApi/CreateFKDayReport Tworzy nowy dokument typu raport dobowy z kasy] * [wiki:DeployerGuide/Others/eDokumentyApi/GetDocumentTypeData Pobierz dane dotyczące typu dokumentu na podstawie jednego z poniższych parametrów] * [wiki:DeployerGuide/Others/eDokumentyApi/RegisterDocument Zarejestruj w dzienniku] * [wiki:DeployerGuide/Others/eDokumentyApi/SearchDocument Wyszukaj dokument] * [wiki:DeployerGuide/Others/eDokumentyApi/GetDocument Pobierz dane dokumentu] * [wiki:DeployerGuide/Others/eDokumentyApi/AddPositionToDocument Dodaj pozycję do dokumentu (produkt)] * [wiki:DeployerGuide/Others/eDokumentyApi/GetPositionsFromDocument Pobierz pozycje dokumentu (produkty)] * [wiki:DeployerGuide/Others/eDokumentyApi/AttachDocumentToProcess Dodaje powiązanie dokumentu ze sprawą (bez ustawienia pola prc_id na dokumencie)] ''' Produkty ''' * [wiki:DeployerGuide/Others/eDokumentyApi/CreateProduct Dodanie nowego produktu] * [wiki:DeployerGuide/Others/eDokumentyApi/UpdateProduct Aktualizacja produktu] * [wiki:DeployerGuide/Others/eDokumentyApi/DeleteProduct Usuwanie produktu] * [wiki:DeployerGuide/Others/eDokumentyApi/SearchProducts Wyszukanie produktów w bazie] * [wiki:DeployerGuide/Others/eDokumentyApi/GetProduct Pobierz dane produktu] ''' Sprawy ''' * [wiki:DeployerGuide/Others/eDokumentyApi/CreateProcess Dodanie nowej sprawy] * [wiki:DeployerGuide/Others/eDokumentyApi/UpdateProcess Aktualizacja sprawy] * [wiki:DeployerGuide/Others/eDokumentyApi/GrantUserAccessToProcess Dodaj pracownika do uprawnionych w sprawie] * [wiki:DeployerGuide/Others/eDokumentyApi/GrantGroupAccessToProcess Dodaj grupę do uprawnionych w sprawie] * [wiki:DeployerGuide/Others/eDokumentyApi/GetProcess Pobierz dane o sprawie] * [wiki:DeployerGuide/Others/eDokumentyApi/SearchProcess Wyszukanie sprawy w bazie] * [wiki:DeployerGuide/Others/eDokumentyApi/AddPositionToProcess Dodaj pozycję do sprawy (produkt)] ''' Kontakty ''' * [wiki:DeployerGuide/Others/eDokumentyApi/CreateContact Dodanie nowego kontrahenta] * [wiki:DeployerGuide/Others/eDokumentyApi/UpdateContact Aktualizuj dane kontrahenta] * [wiki:DeployerGuide/Others/eDokumentyApi/GetContact Pobierz dane o kontrahencie] * [wiki:DeployerGuide/Others/eDokumentyApi/SearchContacts Wyszukanie kontrahentów w bazie] * [wiki:DeployerGuide/Others/eDokumentyApi/GetAddress Pobierz dane adresu] * [wiki:DeployerGuide/Others/eDokumentyApi/CreateContactPerson Dodanie nowej osoby kontaktowej] * [wiki:DeployerGuide/Others/eDokumentyApi/UpdateContactPerson Aktualizuj dane osoby kontaktowej] * [wiki:DeployerGuide/Others/eDokumentyApi/GetContactPersons Pobierz dane wszystkich osób kontaktowych wskazanego kontrahenta] * [wiki:DeployerGuide/Others/eDokumentyApi/MergeContacts Łączenie klientów] * [wiki:DeployerGuide/Others/eDokumentyApi/GetContactPerson Pobierz dane osoby kontaktowej] * [wiki:DeployerGuide/Others/eDokumentyApi/CreateContactUserAccount Tworzy konto pracownika dla klienta] * [wiki:DeployerGuide/Others/eDokumentyApi/UpdateContactUserAccount Aktualizuje konto pracownika przypisane do klienta] ''' Zdarzenia ''' * [wiki:DeployerGuide/Others/eDokumentyApi/CreateEvent Dodaj nowe zdarzenie] * [wiki:DeployerGuide/Others/eDokumentyApi/UpdateEvent Zaktualizuj zdarzenie] * [wiki:DeployerGuide/Others/eDokumentyApi/GetEvent Pobierz dane o zdarzeniu] * [wiki:DeployerGuide/Others/eDokumentyApi/GetEvents Zwraca listę zdarzeń według zadanych parametrów] * [wiki:DeployerGuide/Others/eDokumentyApi/AddAttachmentToEvent Dodaj załącznik do zdarzenia] ''' Procedury ''' * [wiki:DeployerGuide/Others/eDokumentyApi/GetProceduresStages Zwraca dane etapów danej procedury] * [wiki:DeployerGuide/Others/eDokumentyApi/CompleteStage Wykonj dany etap procedury oraz aktywuj następny] ''' Zarządzanie użytkownikami i jednostkami ''' * [wiki:DeployerGuide/Others/eDokumentyApi/GetOrganizationUnit Pobierz dane dotyczące jednostki organizacyjnej na podstawie jednego z poniższych parametrów] * [wiki:DeployerGuide/Others/eDokumentyApi/createUserAccount Dodaje konto użytkownika systemu.] * [wiki:DeployerGuide/Others/eDokumentyApi/deactivateUserAccount Deaktywacja konta użytkownika] * [wiki:DeployerGuide/Others/eDokumentyApi/reactivateUserAccount Ponowna aktywacja konta użytkownika] * [wiki:DeployerGuide/Others/eDokumentyApi/getUserAccount Zwraca dane użytkownika systemu. ] * [wiki:DeployerGuide/Others/eDokumentyApi/getGroup Zwraca dane grupy użytkowników] * [wiki:DeployerGuide/Others/eDokumentyApi/addUserToGroup Dodaje użytkownika do grupy] * [wiki:DeployerGuide/Others/eDokumentyApi/removeUserFromGroup Usuwa użytkownika z grupy] * [wiki:DeployerGuide/Others/eDokumentyApi/createOrganizationUnit Dodaje jednostkę organizacyjną.] * [wiki:DeployerGuide/Others/eDokumentyApi/getOrganizationUnit Zwraca dane jednostki organizacyjnej. ] * [wiki:DeployerGuide/Others/eDokumentyApi/assignUserToOrganizationUnit Przypisuje użytkownika do jednostki organizacyjnej] * [wiki:DeployerGuide/Others/eDokumentyApi/withdrawUserFromOrganizationUnit Zwalnia użytkownika ze stanowiska] * [wiki:DeployerGuide/Others/eDokumentyApi/setUserPrivilages setUserPrivilages] ''' Urządzenia ''' * [wiki:DeployerGuide/Others/eDokumentyApi/createDevice Dodaj nowe urządzenie] * [wiki:DeployerGuide/Others/eDokumentyApi/createDeviceLocation Dodaj lokalizację urządzenia] * [wiki:DeployerGuide/Others/eDokumentyApi/getDevice Pobierz dane urządzenia] * [wiki:DeployerGuide/Others/eDokumentyApi/getDeviceLocation Pobierz lokalizację urządzenia] ''' Inne ''' * [wiki:DeployerGuide/Others/eDokumentyApi/NotifyUser Wysyłanie powiadomień] * [wiki:DeployerGuide/Others/eDokumentyApi/SetFeatureValue Ustawienie cechy] * [wiki:DeployerGuide/Others/eDokumentyApi/SendeInvoiceViaEmail Podpisz i wyślij dokument na emaila] * [wiki:DeployerGuide/Others/eDokumentyApi/getReportData Wykonuje raport i zwraca jego wynik] * [wiki:DeployerGuide/Others/eDokumentyApi/publishDossier Publikacja teczki RWA w danej jednostce organizacyjnej] * [wiki:DeployerGuide/Others/eDokumentyApi/AddComment Dodaj komentarz] ''' MRD ''' * [wiki:DeployerGuide/Others/eDokumentyApi/getRegister Pobranie definicji rejestru] * [wiki:DeployerGuide/Others/eDokumentyApi/addRegisterEntries Dodanie/modyfikacja pozycji w rejestrze] * [wiki:DeployerGuide/Others/eDokumentyApi/addAttachmentToRegisterEntry Dodanie załącznika do wpisu w rejestrze] * [wiki:DeployerGuide/Others/eDokumentyApi/getRegisterEntry Pobranie wpisu z rejestru] * [wiki:DeployerGuide/Others/eDokumentyApi/searchRegisterEntries Wyszukiwanie wpisów w rejestrze] * [wiki:DeployerGuide/Others/eDokumentyApi/getMaxDateForRegister Pobranie daty ostatniej modyfikacji dla całego rejestru] ''' Pliki ''' * [wiki:DeployerGuide/Others/eDokumentyApi/GetFile Pobierz dane o pliku]