Опис

Корпорація Umbrella вирішила інтегрувати в свою екосистему ЕЦП. Для цього вона зареєструвала свій застосунок в eUgoda. Окрім того Umbrella надала eUgoda типовий контракт, який було занесено в систему у вигляді шаблону. На своєму сайті Umbrella дає можливість завантажити і підписати документ ("Договір з файлу") або ж заключити шаблонний договір ("Договір з шаблону"). Після натискання на кнопку-підтвердження сторінка відобразить інформацію про документ:

• Ідентифікатор в системі eUgoda, через яку відбувається підписання
• Ідентифікатор в системі Umbrella
• Посилання сторінку підписання
• Дату, до якої це посилання є валідним

Також внизу буде відображено дві кнопки - "Нове посилання" для створення нового посилання на сторінку підпису, а також "Отримати документ" - для завантаження архіву з документом та підписами.

Інтеграція

Деталі інтеграції можна підглянути у файлі test.js. Для спрощення демонстрації ми не приховуємо applicationId, secret та templateId. Вони задані вгорі файлу.

1. Реєстрація документа

1.1. Зовнішній файл

Після обирання файлу та натискання на "Надіслати" Umbrella робить запит в eUgoda, використовуючи POST-запит на URL https://eugoda.com:3000/api/signing. Параметри передаються в тілі:

• applicationId - ідентифікатор застосунку, виданий eUgoda
• externalId - ідентифікатор документа в Umbrella. Для спрощення ми генеруємо його автоматично: externalId = "umb-" + Math.floor(Date.now() / 1000)
• timestamp - часова мітка запиту (UTC): timestamp = Math.floor(Date.now() / 1000)
• fileName - назва файлу та розширення документa
• content - Вміст документу (рядок base64)
• removeOnCompleted - передаємо true для того, щоб документ було видалено після підписання і надсилання
• validationString - рядок валідації - HMAC, сформований за допомогою алгоритму MD5 з рядка applicationId|externalId|timestamp, використовуючи ключ застосунку, виданий eUgoda:

                    
                      function generateHMAC(data) {
                        // data = "applicationId|externalId|timestamp"
                        const hash = CryptoJS.HmacMD5(data, secret);
                        const ret = hash.toString(CryptoJS.enc.Hex);
                        return ret;
                      }
                    
                  

returnUrl ми лишаємо порожнім, оскільки у нас немає backend-частини. Решта параметрів - за замовчуванням - expectedSignatures = 1 - ми очікуємо лише на один підпис, lifetime = 7200 - посилання буде актуальним протягом двох годин.

1.2. Шаблон

При обиранні "Договір з шаблону" буде відображена форма з параметрами. Після їх заповнення і натискання на "Заключити договір" Umbrella робить запит в eUgoda, використовуючи POST-запит на URL https://eugoda.com:3000/api/signing/template. Параметри передаються в тілі:

• applicationId - ідентифікатор застосунку, виданий eUgoda
• externalId - ідентифікатор документа в Umbrella. Для спрощення ми генеруємо його автоматично: externalId = "umb-" + Math.floor(Date.now() / 1000)
• timestamp - часова мітка запиту (UTC): timestamp = Math.floor(Date.now() / 1000)
• name - назва документу. В нашому випадку вона формується як "Імʼя співробітника - Контракт"
• templateId - ідентифікатор шаблону, виданий eUgoda
• removeOnCompleted - передаємо true для того, щоб документ було видалено після підписання і надсилання
• data - набір параметрів для шаблону. В нашому випадку шаблон очікує такі параметри:

                
                  {
                    name: "...",
                    number: "...",
                    passportNo: "...",
                    passportDate: "2001-01-01",
                    issuer: "...",
                    city: "...",
                    date: "2001-01-01",
                    salary: 5000,
                  }
                
              

• validationString - рядок валідації - HMAC, сформований за допомогою алгоритму MD5 з рядка applicationId|externalId|timestamp, використовуючи ключ застосунку, виданий eUgoda:

                    
                      function generateHMAC(data) {
                        // data = "applicationId|externalId|timestamp"
                        const hash = CryptoJS.HmacMD5(data, secret);
                        const ret = hash.toString(CryptoJS.enc.Hex);
                        return ret;
                      }
                    
                  

returnUrl ми лишаємо порожнім, оскільки у нас немає backend-частини. Решта параметрів - за замовчуванням - expectedSignatures = 1 - ми очікуємо лише на один підпис, lifetime = 7200 - посилання буде актуальним протягом двох годин.

2. Оновлення посилання

При натисканні на "Нове посилання" Umbrella робить запит в eUgoda, використовуючи POST-запит на URL https://eugoda.com:3000/api/signing/share. Параметри передаються в тілі:

• applicationId - ідентифікатор застосунку, виданий eUgoda
• externalId - ідентифікатор документа в Umbrella
• timestamp - часова мітка запиту (UTC): timestamp = Math.floor(Date.now() / 1000)
• validationString - рядок валідації - HMAC, сформований за допомогою алгоритму MD5 з рядка applicationId|externalId|timestamp, використовуючи ключ застосунку, виданий eUgoda:
• isNew - true для створення нового посилання
• removeOnCompleted - передаємо true для того, щоб документ було видалено після підписання і надсилання

Решту параметрів знову лишаєм за замовчуванням.

3. Завантаження архіву з документом та підписами

При натисканні на "Отримати документ" Umbrella робить запит в eUgoda, використовуючи GET-запит на URL https://eugoda.com:3000/api/signing/document. Параметри передаються в рядку запиту:

• applicationId - ідентифікатор застосунку, виданий eUgoda
• externalId - ідентифікатор документа в Umbrella
• timestamp - часова мітка запиту (UTC): timestamp = Math.floor(Date.now() / 1000)
• validationString - рядок валідації - HMAC, сформований за допомогою алгоритму MD5 з рядка applicationId|externalId|timestamp, використовуючи ключ застосунку, виданий eUgoda: