Модуль підписання Doc-Sign-Service


В даній інструкції описані можливості використання Модуля підписання Doc-Sign-Service (надалі просто Модуль підписання), порядок дій для встановлення його, як додатку та реалізоване API (http-запити).

Модуль дозволяє миттєво підписувати велику кількість документів, що створюються в різних облікових системах клієнта.

Загальні схеми інтеграції

Робота з модулем передбачається згідно подальшої схеми: API DocSign <- Облікова система клієнта -> API EDIN 2.0

../../_images/Modul_pidpysannia_Doc_Sign_Service_11.png ../../_images/Modul_pidpysannia_Doc_Sign_Service_12.png

Наприклад, для сервісу ЕТТН схема виглядає наступним чином:

../../_images/Modul_pidpysannia_Doc_Sign_Service_10.png

Технічні вимоги

  1. OC: операційні системи сімейства Linux;

  2. Встановлена Jаva версії 13 і вище;

  3. відкритий доступ до адрес АЦСК, https://iit.com.ua/, а також https://doc-sign.edi-n.com/

Опис програми

Додаток являє собою REST сервер написаний на Java, та розгортається в локальному середовищі.

Запуск та налаштування програми

Наданий архів необхідно розпакувати в окрему директорію (папку). В данній вибраній директорії відкрити термінал та виконати команду запуску.

Команда запуску:

java -jar doc-sign-client-1.0.jar appId appSecret  &>> doc-sign.log &

де:

  • appId і appSecret - дані для доступу

  • doc-sign.log - файл куди буде записуватися лог додатку

За замовчуванням сервер запускається на 8082 порту.

Налаштування сервісу здійснюється за допомогою web інтерфейсу. Налаштування сервісу доступне тільки одному користувачеві (переднастроєному користувачу), користувачам які створені в web інтерфейсі доступні тільки Http запити по API, описані нижче.

Опис web інтерфейсу

Після розгортання сервісу перейдіть за отриманною web адрессою та виконайте вхід за допомогою логіна та пароля.

../../_images/Modul_pidpysannia_Doc_Sign_Service_01.png

Відкриється основна сторінка - Статистика, на якій ви можете отримати основну інформацію про послугу, журнал логів та моживість пошуку по логам.

У блоці Основна інформація доступні дані про Статус послуги та Дату оновлення статусу, скільки Додано ключів, Кількість прийнятих на підпис документів, Кількість успішно підписаних документів та Кількість помилок. У Журналі логів подана інформація про дату та статус підписання, назву документ а також вказано користувача, що здійснив підписання.

../../_images/Modul_pidpysannia_Doc_Sign_Service_06.png

У розділі Ключі доступна інформація про особисті ключі а також форма для додавння ключів. Щоб додати ключ натисніть на кнопку Додати ключ - відкриється вікно для вибору файлу з вашого ПК або носія. Після вибору файлу, необхідно вказати назву ключа (обов’язково) - латинницею, та вказати пароль для ключа (обов’язково) та знову натиснути на Додати ключ.

../../_images/Modul_pidpysannia_Doc_Sign_Service_07.png

У розділі Користувачі можливо додати нового користувача, у якого буде доступ для використання запитів. Для цього натисніть на кнопку Додати користувача та вкажіть логін (обов’язково) - латинницею та без пробілів, та вкажіть пароль для користувача (обов’язково) та натисніть на Додати користувача.

../../_images/Modul_pidpysannia_Doc_Sign_Service_08.png

Нижче знаходиться список користувачів з можливістю редагування або блокування. Наприклад, ви можете змінити пароль або редагувати логін для користувача.

../../_images/Modul_pidpysannia_Doc_Sign_Service_09.png

REST API

REST API сервіс модуля підписання дозволяє:

  • Підписувати вказані файли (.pdf) зазначеним набором ЕЦП

  • Завантажувати архів з підписаним документом (оригінальний файл, файли підписів, файл з візуалізацією підпису)

  • Завантажувати файл з візуалізацією підпису

Авторизація

Для авторизаціїі використовується логін та пароль створеного користувача.

URL

Метод запиту

POST

URL запиту

/api/auth

Headers

Content-Type

multipart/form-data

REQUEST

JSON Body

login (обов’язково) String - логін користувача; password (обов’язково) String - пароль користувача;

RESPONSE

В заголовку відповіді (Response header cookies) в json-форматі передається «ключ сесії» SID, необхідний для подальшої роботи. В кожному наступному запиті (виклику методу) повинен бути присутнім HTTP-заголовок (Header) «Authorization», який повинен містити токен «SID» зі значенням, отриманим при авторизації для коректного виконання запитів.

Тривалість сесії при бездіяльності користувача становить 10 хвилин (мається на увазі, що ключ сесії буде видалено через 10 хвилин, якщо користувач не буде активним (не буде відправляти HTTP запити)).

У відповідь передається код стану HTTP 200 (ok)

Можливі помилки:

  • 401, «Unauthorized» - перевірте введені дані, або перевірте правильність отриманного логіну та паролю.


Відправка документу на підписання

URL

Метод запиту

POST

URL запиту

/api/sign-task

Headers

Content-Type

multipart/form-data

REQUEST

JSON Body

key_names (обов’язково) - список імен ключів у вигляді масиву рядків ([key1,key2]); файл для підписання

RESPONSE

У тілі відповіді при успішному виконанні запиту, прийде uuid завдання, за яким надалі можна отримати результат підписання; у разі помилки - опис помилки.

Можливі помилки:

  • 400, «Bad Request» - при некоректному тілі запиту, або некоректним списком ключів, опис помилки буде зазначено в тілі відповіді.


Отримання листа підписання

URL

Метод запиту

GET

URL запиту

/api/sign-list

URL параметри

task_uuid (обов’язково) - uuid задачі, ідентифікатор отриманий в запиті на отримання документа;

Headers

Content-Type

application / octet-stream

RESPONSE

У тілі відповіді при успішному виконанні запиту, повернеться PDF файл листа підписання (attachment).

Можливі помилки:

  • 404, «Not Found» - вказано некоректний task_uuid;

  • 102, «Processing» - файл ще обробляється, необхідно повторити запит пізніше;

  • 422, «опис помилки» - під час підписання виникла помилка;


Отримання архіву з результатом підписання

URL

Метод запиту

GET

URL запиту

/api/sign-arch

URL параметри

task_uuid (обов’язково) - uuid задачі, ідентифікатор отриманий в запиті на отримання документа;

Headers

Content-Type

application / octet-stream

RESPONSE

У тілі відповіді при успішному виконанні запиту, повернеться ZIP-архів з результатом підписання (вихідний файл, файли підписів, лист підписання).

Можливі помилки:

  • 404, «Not Found» - вказано некоректний task_uuid;

  • 102, «Processing» - файл ще обробляється, необхідно повторити запит пізніше;

  • 422, «опис помилки» - під час підписання виникла помилка;