Wprowadzenie

Symfonia Obieg Dokumentów 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.

 

Sposoby wywołania API

API dla Symfonia Obieg Dokumentów posiada dwa sposoby na wykonywanie połączeń i zapytań:

•przy użyciu SOAP (wymaga autoryzacji)

•lokalnie

 

Wywołanie SOAP

Wywołania SOAP używamy kiedy odwołujemy się do innej maszyny niż obecna. Jeżeli chcesz połączyć się z systemem na obecnej maszynie, użyj rozwiązania połączenia lokalnego. Usługa jest dostępna pod adresem:

https://{host}:{port}/eDokumentyApi.php

 

Wartość {host} oraz {port} należy zamienić odpowiednimi wartościami zgodnymi z konfiguracją serwera instalacyjnego 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.

 

Styl/format dokumentów SOAP

Api może działać w dwóch stylach/formatach:

•RPC/encoded (domyślny). Adres usługi to http://{host}/eDokumentyApi.php (http://{host}/eDokumentyApi.php?wsdl)

•Document/Literal. Adres usługi to http://{host}/eDokumentyApi.php/2 (http://{host}/eDokumentyApi.php/2?wsdl)

 

Przykładowe wywołanie SOAP

Wywołanie SOAP bez nagłówka pliku

require_once('./classes/eDokumentyApi/EDokApiClient.inc');
$ops = array(
    'location' => 'https://{host}:{port}/eDokumentyApi.php',
    "uri" => "eDokumentyAPI",
    'encoding'=>'UTF-8'
);
$client = new EDokApiClient(null, $ops);
$client->setUser('login');
$client->setPass('hasło');
$header = new SoapHeader('eDokumentyAPI', 'entity_symbol', 'demo');
$client->__setSoapHeaders($header);

 

Wywołanie lokalne

Drugim sposobem wywołania jest tzw. wywołanie lokalne. Skrypt można wywołać w przeglądarce z poziomu Symfonia Obieg Dokumentów, np.: poprzez użycie Custom Widgetów.  Skrypt, który będzie się odwoływał do API, nie wymaga podania danych autoryzacyjnych, ponieważ autoryzacja nastąpi na podstawie sesji zalogowanego użytkownika lub ustawiając odpowiednio SysContext, co możemy wykorzystać w lokalnych skryptach wywoływanych cyklicznie przez cron.

 

Przykładowe wywołanie

require_once('./classes/eDokumentyApi/EDokApi.inc');
$api = new EDokApi();
try {
    $res = $api->createContact([]);
} catch (Exception $e) {
    var_dump($e);
}

 

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.

 

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.

$doc_id = NULL;
try {
    $doc_id = $client->createDocument([]);
    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);
    }
}