Універсальний документ (universal document)¶

Універсальний документ - це задача, яка дозволяє створити довільний набір документів для підпису. Це може бути корисно для різних ситуацій, коли потрібно підписати декілька документів одночасно, наприклад при підписанні техніки безпеки, або інших внутрішніх документів компанії.

На відміну від задачі "Відпустка", яка створюється на основі шаблону, універсальний документ створюється без шаблону і дозволяє повністю налаштувати набір документів та підписантів.

Статуси та їх переходи (Status flows)¶

Статуси задачі (Task statuses)¶

Статус	Опис
new	Задача створена, документи можна додавати та редагувати
sending	Виконується асинхронне надсилання документів (масове підписання); задача заблокована
in_progress	Хоча б один документ надіслано на підпис
completed	Всі документи підписані
canceled	Задача скасована

Переходи статусів: new → sending → in_progress → completed або canceled

Статуси документів (Document route statuses)¶

Статус	Опис
new	Документ створений, але не надісланий на підпис
in_progress	Документ надіслано на підпис, очікується підписання
completed	Всі підписанти підписали документ
canceled	Процес підписання скасовано
error	Не вдалося надіслати документ до ЕДО (деталі в `document_info.details`)

Переходи статусів: new → in_progress → completed або canceled

Статуси підписантів (Signer action statuses)¶

Статус	Опис
new	Підписанта додано, але документ не надіслано на підпис
completed	Підписант підписав документ
declined	Підписант відхилив підписання

Переходи статусів: new → completed або declined

Довідник полів (Field reference)¶

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

Поля створення задачі (`POST /universal-document`)¶

Поле	Тип	Опис
`initiator_id`	UUID	ID співробітника, для якого створюється задача (обов'язкове)
`external_id`	string	Ідентифікатор задачі в зовнішніх системах (опціональне)
`manager_id`	UUID	ID менеджера задачі (опціональне)
`name`	string	Назва задачі (опціональне)
`description`	string	Опис задачі (опціональне)

Поля створення документа (`POST /universal-document/{task_id}/document`)¶

Поле	Тип	Опис
`access_settings`	enum	Налаштування доступу до документу: `extended` (розширений) або `private` (приватний) (опціональне, за замовчуванням `null` — використовується значення за замовчуванням системи)
`is_parallel_action`	boolean	Чи можуть підписанти підписувати паралельно (`true`) або послідовно (`false`) (опціональне, за замовчуванням `null`)
`document_info`	object	Додаткова інформація про документ у вигляді JSON (опціональне)
`external_id`	string	Ідентифікатор документа в зовнішніх системах (опціональне)

Поля надсилання документів (`POST /universal-document/{task_id}/send-documents`)¶

Поле	Тип	Опис
`documents_to_send`	array	Масив документів для надсилання на підпис (обов'язкове)
`tags`	array	Масив ID існуючих тегів для документу (опціональне, на рівні документа)
`new_tags`	array	Масив нових тегів для створення та прив'язки до документу (опціональне, на рівні документа)

Детальніше про поля¶

access_settings - визначає хто може бачити документ:

extended - документ можуть бачити всі співробітники з доступом до задачі
private - документ можуть бачити лише підписанти та ініціатор

У публічному API значення за замовчуванням — null (поле не передається й застосовується значення за замовчуванням системи).

is_parallel_action - визначає порядок підписання:

true - всі підписанти можуть підписувати одночасно
false - підписанти підписують послідовно у порядку додавання

У публічному API значення за замовчуванням — null (поле не передається й застосовується значення за замовчуванням системи).

Створення задачі "Універсальний документ"¶

Для створення задачі використовується ендпоінт POST /api/public/v1/universal-document.

При створенні необхідно передати ID співробітника (initiator_id), для якого створюється задача. Опціональними полями є:

external_id - ідентифікатор задачі в зовнішніх системах
manager_id - ID менеджера, який буде управляти задачею
name - назва задачі
description - опис задачі

Перегляд та управління задачами¶

Отримання списку задач¶

Для отримання списку всіх універсальних документів використовується ендпоінт GET /api/public/v1/universal-document.

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

Отримання деталей задачі¶

Для отримання детальної інформації про конкретну задачу використовується ендпоінт GET /api/public/v1/universal-document/{task_id}.

Оновлення задачі¶

Для оновлення інформації задачі (наприклад, опису або статусу) використовується ендпоінт PATCH /api/public/v1/universal-document/{task_id}.

Додавання документів до задачі¶

Основною відмінністю задачі "Універсальний документ" від задачі "Відпустка" є можливість та необхідність додавання довільного набору документів для підпису.

Для додавання документу використовується ендпоінт POST /api/public/v1/universal-document/{task_id}/document.

При додаванні документу можна вказати:

access_settings - налаштування доступу (extended або private)
is_parallel_action - чи можуть підписанти підписувати паралельно
document_info - додаткова інформація у вигляді JSON

Важливо: Додавати та редагувати документи можна лише до моменту надсилання першого документу на підпис (поки статус задачі new).

Перегляд документів задачі¶

Для отримання списку всіх документів задачі використовується ендпоінт GET /api/public/v1/universal-document/{task_id}/document.

Оновлення документу¶

Для оновлення статусу або інформації документу використовується ендпоінт PATCH /api/public/v1/universal-document/{task_id}/document/{document_id}.

Видалення документу¶

Для видалення документу (до надсилання на підпис) використовується ендпоінт DELETE /api/public/v1/universal-document/{task_id}/document/{document_id}.

Завантаження файлів документів¶

Завантаження файлу для підпису¶

Для завантаження файлу документу використовується ендпоінт POST /api/public/v1/universal-document/{task_id}/document/{document_id}/upload.

Завантаження файлу документу¶

Для отримання завантаженого файлу документу використовується ендпоінт GET /api/public/v1/universal-document/{task_id}/document/{document_id}/download.

Управління підписантами¶

Додавання підписанта¶

Для додавання підписанта до документу використовується ендпоінт POST /api/public/v1/universal-document/{task_id}/document/{document_id}/signer.

Ендпоінт приймає ID співробітника (executor_id), який буде підписувати документ. Співробітник повинен мати статус working.

Важливо: Додавати підписантів можна лише до надсилання документу на підпис.

Перегляд підписантів¶

Для отримання списку підписантів та їх статусів використовується ендпоінт GET /api/public/v1/universal-document/{task_id}/document/{document_id}/signer.

Видалення підписанта¶

Для видалення підписанта (до надсилання на підпис) використовується ендпоінт DELETE /api/public/v1/universal-document/{task_id}/document/{document_id}/signer/{executor_id}.

Нагадування підписанту¶

Для надсилання нагадування підписанту використовується ендпоінт POST /api/public/v1/universal-document/{task_id}/document/{document_id}/signer/{executor_id}/remind.

Це може бути корисно, якщо підписант забув про необхідність підписання документу.

Надсилання на підпис¶

Відправка документів на підпис здійснюється через ендпоінт POST /api/public/v1/universal-document/{task_id}/send-documents.

Принцип надсилання документів аналогічний задачі "Відпустка", але враховуючи необмежену кількість документів, відправити можна скільки завгодно документів одночасно. Однак вони повинні йти послідовно - спочатку підписується перший документ (або перші кілька), і наступні не можуть бути надіслані, поки не будуть підписані попередні.

Тіло запиту містить поле documents_to_send — масив документів для надсилання. Кожен елемент масиву ідентифікує документ через document_id і може містити власні поля:

tags - масив ID існуючих тегів для цього документу
new_tags - масив нових тегів для створення та прив'язки до цього документу

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

Додаткові операції¶

Скасування задачі¶

Для скасування задачі використовується ендпоінт POST /api/public/v1/universal-document/{task_id}/cancel.

Маршрути задачі¶

Для отримання списку маршрутів задачі з інформацією про виконавців та статуси використовується ендпоінт GET /api/public/v1/universal-document/{task_id}/route.

Перевизначення підписантів документа¶

Для повного перевизначення списку підписантів документа (видаляє старих і додає нових) використовується ендпоінт POST /api/public/v1/universal-document/{task_id}/document/{document_id}/signers.

Погодження та погоджувачі¶

Для отримання списку маршрутів погодження задачі з інформацією про погоджувачів використовується ендпоінт GET /api/public/v1/universal-document/{task_id}/approval. Для повного перевизначення списку погоджувачів маршруту погодження (видаляє старих і додає нових) використовується ендпоінт POST /api/public/v1/universal-document/{task_id}/approval/{approval_id}/approvers.

Вкладення задачі¶

Для отримання списку додатків (вкладень) задачі використовується ендпоінт GET /api/public/v1/universal-document/{task_id}/attachment.

Очікувана послідовність дій для задачі "Універсальний документ"¶

Створити задачу "Універсальний документ", передавши ID співробітника
Додати документи для підпису
Завантажити файл документу для підпису
Додати підписантів до документу
При необхідності, переглянути список підписантів
Надіслати документи на підпис
При необхідності, надіслати нагадування підписанту
Переглянути статус задачі
При необхідності, завантажити підписаний документ