2.10.4. Docusign

Примітка:

Функціонал Інтеграція з Docusign доступний лише при встановленні додаткового пакета dfx-docusign.

У платформі існує інтеграція з Docusign — сервісом для електронного підпису документів (тип інтеграції: Internal Application). Інтеграція дозволяє користувачу підключати свій обліковий запис Docusign до Scriptum, відправляти файли на підпис та відстежувати статуси конвертів у режимі реального часу.

2.10.4.1. Налаштувати інтеграцію з Docusign

Налаштування інтеграції з Docusign складається з наступних обовʼязкових етапів:

1. Налаштування Docusign — створення профілю розробника, генерація ключів та додавання користувацької конфігурації.
2. Налаштування Scriptum — додавання профілю Docusign у платформі та збереження ключів і параметрів інтеграції.
3. Переведення середовища в робочий режим — активація інтеграції після тестування та подальший перехід у робочий режим.
4. Оновлення налаштування Scriptum робочими даними — після переведення в робочий режим, усі ключі, згенеровані в межах тестового облікового запису, необхідно створити повторно та оновити записи про них у платформі Scriptum.

2.10.4.1.1. Налаштувати Docusign

1. Перейдіть на сайт Docusign developers та створіть профіль:

   1. У правому верхньому куті виберіть Developer account 1, а потім виберіть Create account 2.

      

   2. Заповніть обовʼязкові поля 1, а потім виберіть кнопку Get Started 2.

      

   3. У вікні Check your email введіть в полі 1 код, що надійшов вам на вказану вами поштову скриньку, а потім виберіть Next 2.

      

   4. У вікні Secure Your Account введіть в полі 1 ваш номер телефону, а потім виберіть кнопку Send Code 2.

      

   5. Введіть код, що був надісланий на ваш номер за допомогою SMS-повідомлення.

   6. В полі Password задайте бажаний пароль до вашого профілю.

2. Створіть ключ.

   1. В правому верхньому куті виберіть піктограму профілю 1, а потім виберіть My Apps & Keys 2.

      

   2. Виберіть кнопку Add App and Integration Key.

      

   3. В полі App Name 1 введіть бажану назву, наприклад Scriptum, а потім виберіть кнопку Create App 2.

      

   4. Прогорніть сторінку вниз до секції Service Integration, а потім виберіть кнопку Generate RSA.

      

   5. В секції Private key виберіть піктограму щоб скопіювати ключ, а потім вставте його в безпечне місце, наприклад в нотатки. В наступних етапах інструкції його потрібно буде вставити у відповідне поле в Scriptum.

      
      Увага:

      Після закриття цього вікна, з міркувань безпеки, ви більше не зможете побачити цей ключ. Тому якщо ви не збережете цей ключ, то доведеться генерувати новий.

   6. Прогорніть сторінку вниз до секції Additional settings, а потім виберіть кнопку Add URI.

      

   7. В полі Redirect URIs вставте посилання, на яке Docusign перенаправить користувача після завершення процесу автентифікації. У це поле потрібно вставити посилання на вашу платформу Scriptum у форматі https://your-scriptum-domain/.

      

   8. Прогорніть сторінку вниз до секції Allowed HTTP Methods та установіть усі прапорці методів 1, а потім виберіть кнопку Save 2.

      

3. Додайте користувацьку конфігурацію:

   1. В меню в секції Integrations виберіть пункт Connect.

      

   2. На сторінці Connect виберіть кнопку Add Configuration.

      

   3. Зі списку виберіть Custom.

      

   4. На сторінці Add Custom Configuration в полі Name 1 введіть назву конфігурації, наприклад Scriptum Integration.

   5. В полі URL to Publish 2 вставте посилання за схемою https://<env-url>/docusign/code, де <env-url> — оточення вашої системи, а code – це код профілю Docusign, який ви задасте при додаванні профілю в Scriptum.

      

   6. В розділі Event settings розгорніть вкладку Envelope and Recipients 1, а потім установіть наступні прапорці 2:

      • Envelope Sent
      • Envelope Delivered
      • Envelope Signed/Completed
      • Envelope Declined
      • Envelope Voided
      • Envelope Resent
      • Envelope Corrected
      

      Event Settings (Налаштування подій) — це розділ, який відповідає за відстеження подій, що відбуваються з конвертами і файлами. Актуальні статуси по обраним подіям можна переглянути в ярлику Журнал Docusign.

   7. У вкладці Envelope and Recipients розгорніть дочірню вкладку Include Data.

      

   8. У вкладці Include Data установіть наступні прапорці:

      • Documents
      • Document Fields
      • Templates
      • Recipients
      • Tabs
      

   9. Прогорніть сторінку вниз до секції Associated Users/Groups, а потім виберіть All users (includes new users).

      

   10. Прогорніть сторінку до самого низу, а потім виберіть кнопку Add Configuration.

       

4. Створіть секретний ключ для доступу до конфігурації:

   1. У верхньому меню виберіть Connect Keys.

      

   2. Виберіть кнопку Add Secret Key.

      

   3. В полі зі згенерованим ключем виберіть піктограму , щоб скопіювати ключ, а потім вставте його в безпечне місце, наприклад у нотатки.

      
   Увага:

   Після закриття цього вікна, з міркувань безпеки, ви більше не зможете побачити цей ключ. Тому якщо ви не збережете цей ключ, то доведеться генерувати новий.

2.10.4.1.2. Налаштувати Scriptum

Налаштувати інтеграцію з Docusign може користувач в ролі Developer або Admin.

1. У панелі навігації, виберіть робочий стіл Студія 1.

2. Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Docusign 3.

3. Виберіть ярлик Профіль Docusign 4.

4. У панелі інструментів, виберіть + 5.

   

5. В полі Код введіть код, який ви задали у полі URL to Publish в частині code.

   

6. В полі Імʼя введіть бажане імʼя профілю, наприклад, "Базова інтеграція".

   

7. В полі Integration ID введіть Integration key, що вказаний в налаштуваннях вашого застосунку (App) в Docusign.

   

8. В полі User ID введіть код з поля User ID в налаштуваннях Docusign.

   

   Щоб знайти це поле у ваших налаштуваннях Docusign:

   1. Перейдіть на сайт Docusign developers.

   2. У правому верхньому куті виберіть Developer account 1, а потім виберіть Log in 2.

      

   3. Введіть вашу пошту та пароль для входу в обліковий запис.

      

   4. В правому верхньому куті виберіть піктограму профілю 1, а потім виберіть My Apps & Keys 2.

      

   5. В секції My Account Information біля поля User ID виберіть піктограму , щоб скопіювати значення.

      

9. В полі Приватний RSA ключ вставте ключ, який ви скопіювали в полі Private key під час налаштування Docusign (Див. розділ Налаштувати Docusign > крок 2 > пункт v).

   

10. В полі HMAC секрет вставте ключ, який ви скопіювали в полі Key під час налаштування Docusign (Див. розділ Налаштувати Docusign > крок 4 > пункт iii).

    

11. Docusign автоматично заповнить значення поля URL сповіщення про події після збереження даної форми. Перевірте чи значення відповідає значенню поля URL to Publish в налаштуваннях Docusign.

    

12. У панелі інструментів виберіть піктограму Зберегти.

    

    Після цього система відкриє вікно надання згоди, у якому буде автоматично згенеровано посилання із зазначеними обліковими даними, введеними під час налаштування профілю.

13. Виберіть Відкрити посилання.

    

14. Виберіть Allow Access.

    

    Після підтвердження доступу Docusign перенаправить вас до середовища, URL якого ви зазначили в пункті 2, крок vii розділу 2.10.4.1.1.

15. Введіть свій логін та пароль від вашого облікового запису Scriptum 1, а потім виберіть Увійти 2.

    

2.10.4.1.3. Перевести середовище в робочий режим

1. Відкрийте налаштований вами профіль Docusign:

   1. У панелі навігації, виберіть робочий стіл Студія 1.

   2. Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Docusign 3.

   3. Виберіть ярлик Профіль Docusign 4.

   4. Виберіть потрібний профіль 5.

      

2. Увімкніть перемикач Зробити активним.

   

3. Надішліть 20 успішних API-запитів щоб активувати перехід в робочий режим. Приклади запитів:

   • Оновити шаблони
   • Надіслати документ на підпис у Docusign
   • Переглянути підписи документа у Docusign

Відстежуйте ваші запити в історії подій за допомогою ярлика Журнал Docusign.

Примітка:

Логування API-запитів у Docusign може затримуватися на кілька хвилин, тому ваше тестування інтеграції може не одразу зараховуватися.

4. Перейдіть в Docusign.

5. В правому верхньому куті виберіть піктограму профілю 1, а потім виберіть My Apps & Keys 2.

   

6. В секції Apps and Integration Keys знайдіть створений вами App, а потім в колонці Go Live status виберіть Complete required details.

   

7. В секції Integration Type виберіть Private custom integration.

   

8. Прогорніть сторінку донизу та виберіть Save.

   

9. Придбайте платну підписку для переходу в робочий режим. Зазвичай для невеликих та середніх команд достатньо підписки Starter, адже саме вона підтримує API-інтеграції. Див. Docusign plans and pricing.

   

10. В секції Apps and Integration Keys знайдіть створений вами App, а потім в колонці Go Live status виберіть Submit for review.

11. Дочекайтеся схвалення заявки: Протягом трьох робочих днів ви отримаєте електронний лист, що підтверджує активацію. У статусі додатка з'явиться Review Passed, що дозволить перейти до наступного кроку.

12. Перейдіть у робочий режим:

    1. Після успішного проходження review, у колонці Go Live status виберіть Go Live.

    2. З'явиться вікно для входу (якщо воно не з'явиться, тимчасово дозвольте спливаючі вікна у браузері).

    3. У наступному спливаючому вікні після успішного входу виберіть Production Account та натисніть Select.

    4. Після успішного переходу в робочий режим, у колонці Go Live status ви побачите статус View in production.

       

13. Відкрийте налаштований вами профіль Docusign:

    1. У панелі навігації, виберіть робочий стіл Студія 1.

    2. Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Docusign 3.

    3. Виберіть ярлик Профіль Docusign 4.

    4. Виберіть потрібний профіль 5.

       

14. Внизу сторінки виберіть Перейти в робочий режим.

    

2.10.4.1.4. Оновити налаштування Scriptum робочими даними

Після переведення вашого App у робочий режим DocuSign автоматично перенесе його з безкоштовного developer-облікового запису у новий обліковий запис із платною підпискою. Водночас усі ключі, згенеровані в межах тестового облікового запису, необхідно створити повторно та оновити у платформі Scriptum, щоб забезпечити коректну роботу інтеграції.

1. Перейдіть на сайт Docusign developers та зайдіть у ваш новий обліковий запис із платною підпискою.

2. Виконайте кроки 2-4 з розділу Налаштувати Docusign.

3. Відкрийте налаштований вами профіль Docusign у платформі Scriptum:

   1. У панелі навігації, виберіть робочий стіл Студія 1.

   2. Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Docusign 3.

   3. Виберіть ярлик Профіль Docusign 4.

   4. Виберіть потрібний профіль 5.

      

4. Оновіть значення наступних полів відповідними даними, які ви згенерували у кроці 2:

1 User ID

Введіть код з поля User ID в налаштуваннях Docusign. Щоб знайти це поле у ваших налаштуваннях Docusign:

1. Перейдіть на сайт Docusign developers.

2. В правому верхньому куті виберіть піктограму профілю 1, а потім виберіть My Apps & Keys 2.

   

3. В секції My Account Information біля поля User ID виберіть піктограму , щоб скопіювати значення.

   

2 Приватний RSA ключ

Вставте ключ, який ви скопіювали в полі Private key під час налаштування Docusign. (Див. розділ Налаштувати Docusign > крок 2 > пункт v)

3 HMAC секрет

Вставте ключ, який ви скопіювали в полі Key під час налаштування Docusign. (Див. розділ Налаштувати Docusign > крок 4 > пункт iii).

5. У панелі інструментів виберіть піктограму Зберегти.
6. Знову надайте згоду на користування вашим новим обліковим записом:

   1. Сформуйте посилання для авторизації за такою схемою: https://account.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id=******************&redirect_uri=https://scriptum/environment

      де:

      • https://scriptum/environment — адреса вашого середовища Scriptum (наприклад, https://demo.scriptum.dev/).
      • client_id=****************** — це Integration Key вашого застосунку (App) у Docusign.

      ---

      Приклад: Уявімо, що ваш Integration Key — 9a37258d-e4d2-4ce3-8afb-a5741b79881f, а адреса вашого середовища Scriptum — https://scriptum.dev/.

      У такому випадку посилання для авторизації матиме вигляд: https://account.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id=9a37258d-e4d2-4ce3-8afb-a5741b79881f&redirect_uri=https%3A%2F%2Fscriptum.dev%2F

   2. Перейдіть за сформованим посиланням, а потім виберіть Allow access.

Після цих кроків ваша платформа буде повністю інтегрована з Docusign та готовою до подальших взаємодій з сервісом.

2.10.4.2. Оновити шаблони

Шаблони Docusign — це шаблони із наперед визначеною структурою та ролями підписантів. Вони дозволяють швидко відправляти документи на підпис без потреби щоразу налаштовувати поля вручну. Оновлення шаблонів необхідне для синхронізації з актуальними версіями, створеними безпосередньо у Docusign.

Щоб оновити шаблони:

1. Відкрийте налаштований вами профіль Docusign:

   1. У панелі навігації, виберіть робочий стіл Студія 1.

   2. Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Docusign 3.

   3. Виберіть ярлик Профіль Docusign 4.

   4. Виберіть потрібний профіль 5.

      

2. Перейдіть у вкладку Список шаблонів. В цій вкладці будуть відображені шаблони, що були попередньо налаштовані в обліковому записі Docusign.

   

3. Виберіть кнопку Оновити шаблони.

   

2.10.4.3. Надіслати документ на підпис у Docusign

1. Відкрийте тип документа.

   1. У панелі навігації, виберіть робочий стіл Студія 1.

   2. Виберіть групу ярликів Типи документів 2, а потім виберіть потрібний тип документа 3.

      

2. Перейдіть у вкладку Конструктор.

   

3. Виберіть або додайте файловий атрибут.

   

4. Наведіть курсор на вибраний атрибут, а потім виберіть піктограму , щоб налаштувати дії.

   

5. Установіть прапорці Надіслати до Docusign 1 та Переглянути підписи Docusign 2.

6. Виберіть Зберегти 3.

   

7. У панелі інструментів виберіть піктограму Зберегти A або Зберегти та закрити B.

   

8. Створіть документ даного типу:

   1. У панелі навігації, виберіть робочий стіл Документи 1.
   2. Виберіть ярлик Документи 2, а потім у панелі інструментів виберіть + 3.
   
   3. В полі Тип документа 1 виберіть потрібний тип, а потім виберіть Створити 2.
   

9. На формі документа знайдіть той самий файловий атрибут, для якого активували відповідні Docusign дії.

10. У панелі інструментів атрибута виберіть + та імпортуйте файл з вашого пристрою.

    

    Ви можете імпортувати файли з наступними розширеннями:

    Тип	Підтримувані формати
    Документи	.doc, .docx, .dot, .dotm, .dotx, .htm, .html, .msg, .pdf, .rtf, .txt, .wpd, .xhtml
    Зображення	.bmp, .gif, .heic, .jpg, .jpeg, .png, .tif, .tiff
    Презентації	.pot, .potx, .pps, .ppt, .pptm, .pptx
    Таблиці	.csv, .xls, .xlsm, .xlsx

11. У панелі інструментів виберіть піктограму , щоб надіслати конверт з документом на підпис.

    

12. В полі Імʼя 1 введіть повне ім’я отримувача документа (наприклад, Іван Петренко), а потім в полі Електронна пошта 2 введіть пошту адресата, якому бажаєте відправити документ на підпис.

    
    Примітка:

    Ви також можете скористатись методом заповнення Шаблони Docusign — це шаблони із наперед визначеною структурою та ролями підписантів. Такі шаблони потрібно створювати безпосередньо у Docusign. Див. Create Templates.

13. На картці доданого отримувача виберіть Потрібно підписати, щоб обрати дію, яку має виконати отримувач. Зі списку виберіть одну з наступних дій:

    • Потрібно підписати (Needs to Sign) — ця дія задається усім отримувачам за замовчуванням, поки не вибрана інша. Це дія з максимальними можливостями.
    • Визначення отримувачів (Specify Recipients) — дозволяє вказаному одержувачу вписати ім’я та email для ролей отримувачів, які знаходяться на його ж етапі або пізніше в порядку підписання.
    • Отримання копії (Receives a Copy) — дозволяє надіслати документ отримувачу, який не повинен підписувати або редагувати його. Такий отримувач може переглядати, завантажувати та друкувати документ, але не має права підписувати або змінювати його.
    • Потрібно переглянути (Needs to View) — у цьому випадку одержувач має отримати підписані документи, щоб конверт вважався завершеним, але йому не потрібно (і він не має можливості) підписувати, ставити ініціали, дату чи додавати будь-яку інформацію.
    • Дозволити редагування (Allow to Edit) — дає одержувачу можливість вносити зміни до переліку одержувачів та документа у процесі підписання. Такий одержувач повинен мати дійсний обліковий запис Docusign.
    • Оновлення отримувачів (Update Recipients) — дозволяє призначеному одержувачу редагувати дані інших отримувачів, які ще не підписали документи (тобто підписантів, наступних у черзі підписання).
    
    Примітка:

    Якщо ви додали більше одного одержувача, ви можете встановити порядок підписання. Для цього, в секції Додати отримувачів установіть прапорець Встановити порядок підписання 1, а потім біля карток доданих одержувачів введіть порядкові числа 2.

    

14. В полі Тема електронного листа 1 введіть бажану тему листа, який сповістить адресата про необхідність підписати документ.

15. Виберіть Надіслати 2.

    

2.10.4.4. Переглянути підписи документа у Docusign

1. Відкрийте тип документа.

   1. У панелі навігації, виберіть робочий стіл Студія 1.

   2. Виберіть групу ярликів Типи документів 2, а потім виберіть потрібний тип документа 3.

      

2. Перейдіть у вкладку Конструктор.

   

3. Виберіть або додайте файловий атрибут.

   

4. Наведіть курсор на файловий атрибут, а потім виберіть піктограму , щоб налаштувати дії.

   

5. Установіть прапорці Надіслати до Docusign 1 та Переглянути підписи Docusign 2.

6. Виберіть Зберегти 3.

   

7. У панелі інструментів виберіть піктограму Зберегти A або Зберегти та закрити B.

   

8. Створіть документ на основі даного типу документа:

   1. У панелі навігації, виберіть робочий стіл Документи 1.
   2. Виберіть ярлик Документи 2, а потім у панелі інструментів виберіть + 3.
   
   3. В полі Тип документа 1 виберіть потрібний тип, а потім виберіть Створити 2.
   

9. На формі документа знайдіть той самий файловий атрибут, для якого активували відповідні Docusign дії.

10. У панелі інструментів атрибута виберіть + та імпортуйте будь-який файл з вашого пристрою.

    

11. У панелі інструментів виберіть піктограму , щоб переглянути підписи, що були нанесені у платформі Docusign.

    

12. Ви побачите вікно Результат перевірки підпису. Якщо статус підписання — Завершено, ви можете завантажити підписаний документ. Для цього виберіть піктограму .

    

Примітка:

Ви також можете скопіювати унікальний код конверта, щоб відстежувати його статус у ярлику Конверти Docusign.

2.10.4.5. Переглянути історію подій Docusign

В ярлику Журнал Docusign ви можете переглянути усі події та зміни статусів конвертів, відправлених через інтеграцію. Це дозволяє відстежувати процес надсилання та підписання документів у реальному часі.

1. У панелі навігації, виберіть робочий стіл Студія 1.

2. Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Docusign 3.

3. Виберіть ярлик Журнал Docusign 4.

   

2.10.4.6. Переглянути конверти Docusign

В ярлику Конверт Docusign ви можете переглянути всі створені та відправлені через інтеграцію конверти. Тут відображаються їхні статуси, теми та пов'язані сутності, що дозволяє швидко знаходити потрібні документи та контролювати їхній стан.

1. У панелі навігації, виберіть робочий стіл Студія 1.

2. Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Docusign 3.

3. Виберіть ярлик Конверти Docusign 4.