Jak zintegrować się z AMODIT za pomocą REST API

Wprowadzenie

Niniejszy dokument jest swego rodzaju szybkim przewodnikiem (ang. a quick guide) po tym, jak zintegrować się z systemem AMODIT za pomocą dostępnego w nim REST API. W dokumencie przedstawiliśmy kilka typowych scenariuszy użycia AMODIT REST API, co powinno umożliwić sprawną realizację (dwustronnej) integracji zewnętrznego systemu z systemem AMODIT.

Dokumentacja AMODIT REST API

Podstawowym źródłem wiedzy o AMODIT REST API są poniższe dwie strony:

Konfiguracja dostępu do REST API po stronie AMODIT

AMODIT REST API jest modułem odrębnie licencjonowanym, a więc płatnym. Należy skontaktować się z Działem Sprzedaży Astrafox w celu pozyskania licencji. UWAGA! Konfigurację przedstawioną w tym rozdziale przeprowadza administrator systemu AMODIT. Konfiguracja dostępu do AMODIT REST API składa się zasadniczo z dwóch głównych kroków:

  • Weryfikacja włączenia modułu REST API w kluczu licencyjnym. restapi01_klcz_lcncjn
  • Konfiguracja danych dostępowych. restapi02_ustwn_1-5 Moduł zarządzania dostępami do REST API dostępny jest w ustawieniach systemowych …
  • [1, 2] … w zakładce „Integracje AMODIT”
  • [3] … w sekcji „RestAPI”
  • [4] … pod przyciskiem „Rest API Credentials” [5]. restapi03_ustwn_6-11 Parametry dostępu do REST API:
  • [6] nazwa instancji dostępu (może być wiele instancji);
  • [7] identyfikator klienta (generowany automatycznie);
  • [8] klucz klienta (generowany automatycznie);
  • [9] użytkownik systemowy(!) reprezentujący daną instancję dostępu (w historii sprawy będą rejestrowane na konto tego użytkownika wszelkie operacje wykonywane za pomocą REST API);
  • [10] data ważności dostępu;
  • [11] zakres dostępu (dopuszczalne wartości: casesRead, casesEdit).

UWAGA! Na potrzeby integracji stronie, która chce korzystać z REST API, należy przekazać wartości parametrów [7], [8] i [11].

Przykłady użycia AMODIT REST API

W tym rozdziale przedstawiamy najczęściej występujące scenariusze (przykłady) użycia AMODIT REST API, a są to:

  • Pobieranie danych ze sprawy;
  • Aktualizacja danych na sprawie;
  • Pobieranie zawartości załącznika na sprawie;
  • Aktualizacja zawartości załącznika na sprawie;
  • Tworzenie sprawy.

UWAGA! Zrzuty ekranów umieszczone w poszczególnych przykładach pochodzą z aplikacji Postman link do pobrania: https://www.postman.com/downloads/.

Ustawienia autoryzacji

Przed skorzystaniem z AMODIT REST API należy ustawić odpowiednie parametry autoryzacji. W tym celu należy wykonać poniższe kroki (w aplikacji Postman):

  • [1] w ustawieniach projektu (kolekcji) przejść do zakładki „Authorization”;
  • [2] Auth Type: Oauth 2.0;
  • [3] Add auth data to: Request Headers;
  • [4] Header Prefix: Bearer postman01_auth_1-4
  • [5] Token Name: {dowolna nazwa identyfikująca instancję połączenia};
  • [6] Grant type: Client Credentials;
  • [7] Access/Refresh Token URL: https://{adres_serwera_amodit}/restapi/v1/token;
  • [8] Client ID: {identyfikator klienta ustawiony w AMODIT};
  • [9] Client Secret: {klucz klienta};
  • [10] Scope: casesRead casesEdit;
  • [11] Client Authentication: Send as Basic Auth header. postman02_auth_5-11

Przykład 1 – pobieranie danych ze sprawy

Przykład pobierania danych ze sprawy metodą GET:

Przykład 2 – aktualizacja danych na sprawie

Przykład aktualizacji sprawy za pomocą metody PUT:

  • [16] dla konkretnej sprawy użyć endpointa: https://{adres_serwera_amodit}/restapi/v1/cases/{id_sprawy}
  • [17] ustawić komunikat żądania (ang. request body) …
  • [18] … w postaci JSON;
  • [19] wysłać żądanie;
  • [20] komunikat odpowiedzi (ang. response body) dla poprawnie wykonanej operacji. postman04_put_16-20

Przykład 3 – pobieranie zawartości załącznika na sprawie

Przykład pobrania zawartości załącznika z wybranego pola typu dokument na sprawie za pomocą metody GET:

  • dla konkretnej sprawy użyć endpointa: https://{adres_serwera_amodit}/restapi/v1/cases/{id_sprawy}
  • [21] przekazać w parametrach nazwę pola typu dokument w postaci: {nazwa pola}[attValue,attName]
  • w odpowiedzi z systemu odnaleźć obiekt reprezentujący pole typu dokument [21] …
  • [22] … a następnie atrybut „attValue”
  • [23] w atrybucie „value” będzie się znajdować zawartość pliku zakodowana w formacie base64. postman05_get_21-23

Przykład 4 – aktualizacja zawartości załącznika na sprawie

Przykład aktualizacji zawartości załącznika dla wybranego pola typu dokument na sprawie za pomocą metody PUT:

  • dla konkretnej sprawy użyć endpointa: https://{adres_serwera_amodit}/restapi/v1/cases/{id_sprawy}
  • [24] do JSON dodać obiekt reprezentujący pole typu dokument na sprawie – w atrybucie „name” podać nazwę pola, …
  • [25] … a w atrybucie „value” podać zawartość pliku w następującej postaci: {nazwa pliku};{zawartość pliku zakodowana w formacie base64} postman06_put_24-25

Przykład 5 – tworzenie sprawy

Przykład tworzenia sprawy dla wybranego procesu za pomocą metody POST:

  • [26] użyć endpointa: https://{adres_serwera_amodit}/restapi/v1/cases/
  • [27] w JSON żądania w atrybucie „caseProcedure” podać nazwę procesu, dla którego będzie tworzona sprawa;
  • [28] w atrybucie „caseStatus” wprowadzić nazwę etapu, od którego ma się rozpocząć obieg sprawy;
  • [29] w kolekcji „fields” wprowadzić nazwy pól i wartości, którymi ma być wstępnie wypełniona tworzona sprawa;
  • [30] w odpowiedzi REST API zwróci identyfikator utworzonej sprawy „caseId”. postman07_post_26-30
Aktualizacja