Ідентифікатор документа eUgoda: | |
Ідентифікатор документа Umbrella: | |
Посилання для підпису: | |
Активне до: |
Опис
Корпорація 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
- ідентифікатор застосунку, виданий eUgodaexternalId
- ідентифікатор документа в Umbrella. Для спрощення ми генеруємо його автоматично:externalId = "umb-" + Math.floor(Date.now() / 1000)
timestamp
- часова мітка запиту (UTC):timestamp = Math.floor(Date.now() / 1000)
fileName
- назва файлу та розширення документacontent
- Вміст документу (рядок 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
- ідентифікатор застосунку, виданий eUgodaexternalId
- ідентифікатор документа в Umbrella. Для спрощення ми генеруємо його автоматично:externalId = "umb-" + Math.floor(Date.now() / 1000)
timestamp
- часова мітка запиту (UTC):timestamp = Math.floor(Date.now() / 1000)
name
- назва документу. В нашому випадку вона формується як "Імʼя співробітника - Контракт"templateId
- ідентифікатор шаблону, виданий eUgodaremoveOnCompleted
- передаємо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
- ідентифікатор застосунку, виданий eUgodaexternalId
- ідентифікатор документа в Umbrellatimestamp
- часова мітка запиту (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
- ідентифікатор застосунку, виданий eUgodaexternalId
- ідентифікатор документа в Umbrellatimestamp
- часова мітка запиту (UTC):timestamp = Math.floor(Date.now() / 1000)
validationString
- рядок валідації - HMAC, сформований за допомогою алгоритму MD5 з рядкаapplicationId|externalId|timestamp
, використовуючи ключ застосунку, виданий eUgoda: