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

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

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

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

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

Статус	Опис
new	Задача створена, документи можна додавати та редагувати
in_progress	Хоча б один документ надіслано на підпис
completed	Всі документи підписані
canceled	Задача скасована

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

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

Статус	Опис
new	Документ створений, але не надісланий на підпис
in_progress	Документ надіслано на підпис, очікується підписання
completed	Всі підписанти підписали документ
canceled	Процес підписання скасовано

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

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

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

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

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

Поле	Тип	Опис
`initiator_id`	integer	ID співробітника, для якого створюється задача (обов'язкове)
`external_id`	string	Ідентифікатор задачі в зовнішніх системах (опціональне)
`manager_id`	integer	ID менеджера задачі (опціональне)
`name`	string	Назва задачі (опціональне)
`description`	string	Опис задачі (опціональне)
`access_settings`	enum	Налаштування доступу до документу: `extended` (розширений) або `private` (приватний) (опціональне, за замовчуванням `extended`)
`is_parallel_action`	boolean	Чи можуть підписанти підписувати паралельно (`true`) або послідовно (`false`) (опціональне, за замовчуванням `false`)
`document_info`	object	Додаткова інформація про документ у вигляді JSON (опціональне)
`tags`	array	Масив ID існуючих тегів для документу (опціональне)
`new_tags`	array	Масив нових тегів для створення та прив'язки до документу (опціональне)

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

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

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

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

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

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

Для створення задачі використовується ендпоінт 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 - масив документів для надсилання
tags - теги для кожного документу
new_tags - нові теги для створення

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

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