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
define('EDOK_API_LOGIN', 'edok_api_user');
define('EDOK_API_PASSWORD', 'edok_api_pass');

// Dodatkowa stała która umożliwia pominięcie autentykacji (jeśli ustawiamy na FALSE to nie sprawdza danych EDOK_API_LOGIN i EDOK_API_PASSWORD)
// domyślnie ustawiona na TRUE, można wysłać GET lub dodatkowe nagłówki WSS
// define('EDOK_API_AUTH_MODE', TRUE);
?>

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
ini_set('display_errors', 'On');

define('EDOK_API_LOGIN', 'user');
define('EDOK_API_PASSWORD', 'password');
define('DEFAULT_ENTITY_SYMBOL', 'demo');

$ops = array(
    'location' => '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

Produkty

Sprawy

Kontakty

Zdarzenia

Procedury

Zarządzanie użytkownikami i jednostkami

Urządzenia

Inne

MRD

Pliki

Załączniki