Користувацька заявка (Custom Request)¶

Користувацька заявка — це задача довільного типу, яку компанія налаштовує самостійно у вигляді шаблону: визначає назву, категорію, перелік документів, маршрути підписання та погодження. На основі активного шаблону створюються задачі «Заявка», у межах яких формуються, погоджуються та підписуються документи.

Налаштування структури шаблону задачі «Заявка» (документи, маршрути, поля) доступне лише через вебінтерфейс Вчасно.Кадри. Публічний API дозволяє керувати шаблонами на рівні метаданих, створювати задачі на основі активних шаблонів, керувати документами, підписантами й погоджувачами, а також отримувати статус і підписані файли — що й використовується для інтеграції зі сторонніми ERP.

Статуси та їх переходи¶

Статуси задачі¶

Статус	Опис
`new`	Задача створена, документи можна додавати та редагувати
`in_progress`	Хоча б один документ відправлено на підписання / триває погодження
`completed`	Усі документи підписані, задача завершена
`canceled`	Задача скасована

Переходи: new → in_progress → completed або canceled.

Статуси маршруту¶

Статус	Опис
`new`	Маршрут створений, але ще не активний
`in_progress`	Маршрут активний (документи на підписанні або погодження триває)
`completed`	Маршрут завершений
`canceled`	Маршрут скасований

Статуси документа¶

Статус	Опис
`new`	Документ створений, але ще не відправлений на підписання
`in_progress`	Документ на підписанні
`completed`	Документ підписаний усіма підписантами
`canceled`	Документ скасований

Статуси підписанта / погоджувача¶

Статус	Опис
`new`	Підписанта (погоджувача) додано, документ ще не надіслано
`completed`	Підписант підписав (погоджувач погодив) документ
`declined`	Підписант відхилив підписання (погоджувач відхилив погодження)

Статуси шаблону задачі (`TaskTemplateStatus`)¶

Статус	Опис
`active`	Активний шаблон, доступний для створення задач
`inactive`	Неактивний шаблон
`superseded`	Замінений новою версією
`archived`	Архівований

Шаблони задачі «Заявка»¶

Шаблон задається версією (version_identifier). Метадані шаблону можна отримувати, створювати та оновлювати через API.

Поля шаблону у відповіді (`PublicApiRetrieveCustomRequestTemplateSerializer`)¶

Поле	Тип	Опис
`version_identifier`	UUID	Ідентифікатор версії шаблону
`type`	TaskTemplateType	Тип шаблону
`name`	string	Назва шаблону
`category`	string \| null	Категорія шаблону
`status`	TaskTemplateStatus	Статус шаблону (`active`, `inactive`, `superseded`, `archived`)
`is_employee_initiation_allowed`	bool	Чи може співробітник самостійно ініціювати задачу
`is_leader_employee_initiation_allowed`	bool	Чи може керівник ініціювати задачу за співробітника

Поля для створення шаблону (`PublicApiCreateCustomRequestTemplateSerializer`)¶

Поле	Тип	Опис	Обов'язкове
`name`	string	Назва шаблону	Так
`category`	string	Категорія шаблону	Ні
`is_employee_initiation_allowed`	bool	Чи може співробітник ініціювати задачу (за замовчуванням `true`)	Ні
`is_leader_employee_initiation_allowed`	bool	Чи може керівник ініціювати задачу за співробітника (за замовчуванням `false`)	Ні

Поля для оновлення шаблону (`PublicApiUpdateCustomRequestTemplateSerializer`)¶

Усі поля необов'язкові; передаються лише ті, що змінюються: name, category, status, is_employee_initiation_allowed, is_leader_employee_initiation_allowed.

Операції над шаблонами¶

Список доступних шаблонів та отримання шаблону за version_identifier:

Створення та оновлення шаблону:

Поля для створення задачі «Заявка»¶

(PublicApiCreateCustomRequestSerializer)

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

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

(PublicApiRetrieveCustomRequestSerializer)

Поле	Тип	Опис
`id`	UUID	ID задачі
`initiator_id`	UUID	ID співробітника-ініціатора
`manager_id`	UUID \| null	ID менеджера задачі
`template_version_identifier`	UUID	Ідентифікатор версії шаблону задачі
`type`	TaskTemplateType	Тип шаблону задачі
`category`	string \| null	Категорія задачі
`status`	TaskStatus	Статус задачі: `new`, `in_progress`, `completed`, `canceled`
`description`	string \| null	Опис задачі
`cancellation_reason`	string \| null	Причина скасування задачі
`cancelled_by`	TaskCancelledByType \| null	Хто скасував: `initiator`, `manager`, `api`, `document_decline`
`cancelled_by_employee_id`	UUID \| null	ID співробітника, який скасував задачу
`cancelled_by_user_id`	UUID \| null	ID користувача, який скасував задачу
`cancellation_date`	datetime \| null	Дата скасування задачі
`external_id`	string \| null	Зовнішній ID задачі
`name`	string \| null	Назва задачі
`date_created`	datetime	Дата створення задачі
`date_updated`	datetime	Дата останнього оновлення задачі

Очікувана послідовність дій для задачі «Заявка»¶

Отримати список активних шаблонів і обрати потрібний version_identifier
Створити задачу «Заявка» на основі шаблону
Отримати створену задачу
Отримати список маршрутів задачі
Отримати список документів задачі
За потреби створити додатковий документ
За потреби завантажити файл для документа
Отримати список підписантів документа
За потреби додати, видалити або перевизначити підписантів
Відправити документи на підписання. В тілі запиту для кожного документа можна передати теги (tags, new_tags)
За потреби надіслати нагадування підписанту
Скачати підписаний документ

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

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

Оновити статус, назву, менеджера або причину скасування задачі можна через PATCH /api/public/v1/custom-request/{task_id}:

Доступні для оновлення поля (PublicApiUpdateCustomRequestSerializer): name, status, cancellation_reason, manager_id.

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

Обов'язкове поле cancellation_reason.

Маршрути погодження¶

Отримати маршрути погодження та перевизначити список погоджувачів:

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

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

Інтеграція з ERP: періодичне отримання завершених документів¶

Типовий сценарій для ERP: періодично (наприклад, раз на 5–15 хвилин) опитувати API Вчасно.Кадри, отримувати список завершених задач «Заявка», забирати підписані файли та застосовувати зміни у власній системі.

1. Отримати список завершених задач¶

GET /api/public/v1/custom-request повертає сторінкований список задач і підтримує серверну фільтрацію.

Ключові параметри запиту:

Параметр	Тип	Призначення
`status__in`	array[TaskStatus]	Фільтр за статусом задачі. Для ERP-polling вкажіть `completed`, за потреби додайте `canceled`
`start_date`	date	Початок періоду (за `date_created` задачі)
`end_date`	date	Кінець періоду
`external_id__in`	array[string]	Пошук задач за зовнішніми ідентифікаторами, якими їх було створено з ERP
`initiator__in`	array[UUID]	Фільтр за співробітниками-ініціаторами
`manager__in`	array[UUID]	Фільтр за менеджером задачі
`task_template__in`	array[UUID]	Фільтр за ID шаблонів задач
`task_template_type__in`	array[TaskTemplateType]	Фільтр за типом шаблону
`is_approved`	boolean	`true` — задачу успішно погоджено; `false` — погодження скасовано
`is_approval_needed`	boolean	`true` — є незавершене погодження; `false` — погодження не потрібне або вже завершене
`search`	string	Повнотекстовий пошук
`page`, `size`	int	Пагінація

Рекомендований polling-запит: GET /api/public/v1/custom-request?status__in=completed&start_date={остання_перевірка}. ERP повинна зберігати дату останнього успішного опитування та на кожній ітерації вичитувати всі сторінки результату.

Для дедуплікації слід використовувати поле external_id: ERP задає його при створенні задачі або перевіряє при обробці вже існуючих задач, щоб не обробити одну й ту саму заявку двічі.

2. Отримати повну інформацію про задачу¶

GET /api/public/v1/custom-request/{task_id} повертає один об'єкт зі структурою, описаною в таблиці «Поля у відповіді при отриманні задачі».

3. Отримати документи задачі¶

GET /api/public/v1/custom-request/{task_id}/document — список документів у межах задачі.

Поля елемента списку (PublicApiListCustomRequestDocumentSerializer):

Поле	Тип	Опис
`id`	UUID	ID документа
`name`	string	Назва документа
`status`	TaskRouteStatus	Статус документа (`new`, `in_progress`, `completed`, `canceled`)
`document_type`	TaskDocumentType	Тип документа
`access_settings`	enum \| null	`extended` або `private`
`is_parallel_action`	bool \| null	Паралельний режим підпису
`document_info`	object \| null	Метадані файлу (розмір, mime-type тощо)
`edo_document_id`	string \| null	ID документа у системі ЕДО (Вчасно.ЕДО), якщо синхронізовано
`external_id`	string \| null	Зовнішній ID документа

4. Завантажити підписаний файл¶

GET /api/public/v1/custom-request/{task_id}/document/{document_id}/download повертає бінарний вміст файлу. Рекомендовано звертатися до цього ендпоінта лише для документів у статусі completed.

5. Отримати статус підписантів¶

GET /api/public/v1/custom-request/{task_id}/document/{document_id}/signer повертає список підписантів документа та їхній статус.

Поля (PublicApiRetrieveDocumentSignerSerializer):

Поле	Тип	Опис
`executor_id`	UUID	ID співробітника-підписанта
`status`	TaskRouteActionStatus	Статус дії підписанта: `new`, `completed`, `declined`

Приклади запитів та відповідей¶

Повні OpenAPI-приклади (зі згенерованими зразками тіл запитів і відповідей) завжди актуальні в Swagger UI:

Swagger UI{target=_blank}
Redoc{target=_blank}

Блоки <swagger-ui> вище підтягують приклади безпосередньо з живої OpenAPI-схеми, тому вони завжди відповідають реальному API.

Структури даних для вкладених об'єктів¶

Документ на підписання при створенні (`PublicApiCreateCustomRequestDocumentSerializer`)¶

Поле	Тип	Опис	Обов'язкове
`access_settings`	enum	`extended` або `private`	Ні
`is_parallel_action`	bool	Паралельний режим підпису	Ні
`document_info`	object	Метадані файлу	Ні
`external_id`	string	Зовнішній ID документа	Ні

Підписант документа¶

Додавання одного підписанта (PublicApiCreateDocumentSignerSerializer):

Поле	Тип	Опис	Обов'язкове
`executor_id`	UUID	ID співробітника-підписанта (у статусі `working`)	Так

Перевизначення списку підписантів (PublicApiOverrideDocumentSignersSerializer) — поле signers зі списком об'єктів { "executor_id": UUID } (видаляє попередніх підписантів і додає нових).

Маршрут задачі (`PublicApiListVacationRouteSerializer`)¶

Поле	Тип	Опис
`id`	UUID	ID маршруту
`name`	string	Назва маршруту
`order`	int	Порядок у задачі
`route_type`	PublicDocumentType	Тип маршруту
`status`	TaskRouteStatus	Статус
`is_parallel_action`	bool \| null	Паралельний режим виконання
`access_settings`	enum \| null	`extended` або `private`
`document_type`	TaskDocumentType \| null	Тип документа (для документних маршрутів)
`external_id`	string \| null	Зовнішній ID
`actions`	array[RouteAction]	Список дій (підпис/погодження)
`date_created` / `date_updated`	datetime	Дати створення/оновлення

Елемент actions[*] (PublicApiRouteActionSerializer):

Поле	Тип	Опис
`id`	UUID	ID дії
`executor_id`	UUID \| null	ID виконавця (підписанта/погоджувача)
`manager_id`	UUID \| null	ID менеджера, що делегував дію
`order`	int	Порядковий номер дії
`status`	TaskRouteActionStatus	`new`, `completed`, `declined`
`action_type`	DocumentActionType \| null	Тип дії
`decline_reason`	string \| null	Причина відхилення
`date_created` / `date_updated`	datetime	Дати

Маршрут погодження (`PublicApiApprovalRouteSerializer`)¶

Поле	Тип	Опис
`id`	UUID	ID маршруту погодження
`name`	string	Назва
`order`	int	Порядок
`status`	TaskRouteStatus	Статус маршруту
`is_parallel_action`	bool \| null	Паралельний режим
`approvers`	array[ApprovalStep]	Список погоджувачів

Елемент approvers[*] (PublicApiApprovalStepSerializer):

Поле	Тип	Опис
`id`	UUID	ID кроку погодження
`executor_id`	UUID	ID співробітника-погоджувача
`order`	int	Порядковий номер
`status`	TaskRouteActionStatus	`new`, `completed`, `declined`

Перевизначення погоджувачів (PublicApiOverrideApprovalStepsSerializer) — поле steps зі списком об'єктів { "executor_id": UUID, "order": int | null } та необов'язкове is_parallel_action.

Вкладення задачі (`PublicApiTaskAttachmentSerializer`)¶

Поле	Тип	Опис
`id`	UUID	ID вкладення
`employee_id`	UUID	ID співробітника, до якого прив'язане вкладення
`media_file_id`	UUID	ID медіафайлу
`attachment_type`	TaskAttachmentType \| null	Тип вкладення

Контекст відправлення документів (`SendCustomRequestDocumentsSerializer`)¶

Під час виклику POST /api/public/v1/custom-request/{task_id}/send-documents тіло містить documents_to_send[], де кожен елемент:

Поле	Тип	Опис	Обов'язкове
`document_id`	UUID	ID документа, який відправляється на підписання	Так
`tags`	array[UUID]	Список ID наявних тегів документа	Ні
`new_tags`	array[string]	Список назв нових тегів для створення	Ні

Можна передати один або декілька документів, але вони всі повинні бути розташовані послідовно в маршруті задачі. Можливість відправки декількох документів одночасно залежить від налаштувань шаблону задачі.

Дозволені формати файлів для завантаження¶

При завантаженні документів через POST /api/public/v1/custom-request/{task_id}/document/{document_id}/upload підтримуються: PNG, JPEG, JPG, SVG, PDF, XLS, XLSX, CSV, DOC, DOCX, TXT, XML.

Важливі моменти¶

Шаблон задачі — задачу «Заявка» можна створити лише на основі активного шаблону (status = active). Структура документів і маршрутів визначається шаблоном.
Ідемпотентність для ERP — використовуйте external_id при створенні задач і при подальшому пошуку (external_id__in), щоб безпечно ретраїти запити і не дублювати записи в ERP.
Порядок відправлення документів — документи можна відправляти послідовно або одночасно залежно від налаштувань шаблону. Якщо шаблон передбачає послідовне підписання, наступний документ можна надіслати лише після повного підписання попереднього.
Зміна підписантів — додавати, видаляти та перевизначати підписантів можна лише до моменту відправлення документа на підписання.
Підписанти зі статусом working — як підписантів можна використовувати лише співробітників у статусі working.