Масовий підпис (bulk signing)¶

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

На відміну від задачі «Універсальний документ», де ви формуєте довільний набір документів і додаєте підписантів до кожного, у масовому підписі документ один, а список підписантів — це отримувачі задачі (initiator_ids).

Особливості публічного API¶

• Усі запити авторизуються заголовком X-Vchasno-Public-Token (див. Початок роботи). Компанія визначається з токена — передавати company_id не потрібно.
• Шаблон задачі автоматично береться зі стандартного шаблону масового підпису компанії — передавати ідентифікатор шаблону не потрібно.
• Список підписантів задається лише при створенні задачі через initiator_ids. Окремих ендпоінтів для додавання/видалення підписантів немає.
• Задача містить рівно один документ. Завантаження документа одночасно і зберігає файл, і будує маршрут підписання — окремого кроку налаштування маршруту немає.
• Надсилання відбувається асинхронно: запит одразу повертає задачу зі статусом sending (HTTP 202 Accepted), а фактична відправка документів до ЕДО виконується у фоні. Результат слід відстежувати опитуванням (GET .../{task_id}, .../signers, .../signers/counts).
• Успішні відповіді (окрім скачування файлів та нагадування одному підписанту) загорнуті в об'єкт {"detail": ...}. Списки додатково містять поля пагінації (total, page, size, items).

Перелік ендпоінтів¶

Усі шляхи мають префікс /api/public/v1/bulk-signing.

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

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

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

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

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

Статуси підписантів-отримувачів (Signer action statuses)¶

Повертаються у полі status кожного підписанта (GET .../signers).

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

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

Створення задачі (POST /bulk-signing)¶

Завантаження документа (POST /bulk-signing/{task_id}/document)¶

multipart/form-data, поле file — файл документа. Тіла у форматі JSON немає.

Скасування задачі (POST /bulk-signing/{task_id}/cancel)¶

Об'єкт задачі у відповіді (PublicApiBulkSigningRetrieveSerializer)¶

Об'єкт підписанта у відповіді (BulkSigningSignerSerializer)¶

Лічильники підписантів (SignerCountsSerializer)¶

Створення задачі «Масовий підпис»¶

Ендпоінт POST /api/public/v1/bulk-signing. Передайте назву задачі (name) та список ID отримувачів (initiator_ids). Компанія та шаблон визначаються автоматично з токена.

Приклад запиту:

curl -X POST 'https://kadry.vchasno.ua/api/public/v1/bulk-signing' \
  -H 'X-Vchasno-Public-Token: <ваш_токен>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Ознайомлення з наказом №42",
    "initiator_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "b2c3d4e5-6f70-4a1b-8c2d-3e4f5a6b7c8d"
    ],
    "description": "Ознайомлення всіх працівників відділу з новим наказом",
    "end_date": "2026-08-15"
  }'

Приклад відповіді (201):

{
  "detail": {
    "id": "9a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7a8b",
    "name": "Ознайомлення з наказом №42",
    "status": "new",
    "end_date": "2026-08-15",
    "initiator_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "b2c3d4e5-6f70-4a1b-8c2d-3e4f5a6b7c8d"
    ]
  }
}

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

Ендпоінт POST /api/public/v1/bulk-signing/{task_id}/document (multipart/form-data, поле file).

Цей крок робить одразу дві речі: зберігає файл і будує маршрут підписання з отримувачів (initiator_ids). Окремого ендпоінта для налаштування маршруту немає — підписантів задавати не потрібно, вони беруться зі списку отримувачів задачі.

Особливості:

• Задача містить рівно один документ. Повторне завантаження замінює попередній документ і його маршрут.
• Замінити (або завантажити) документ можна лише поки задача ще не почала надсилатися: статус має бути new чи in_progress, і жоден крок підписання не має вийти за межі статусу new. Після початку надсилання спроба завантаження поверне помилку (Document cannot be replaced after sending has started), щоб не знищити вже наявні підписи.

У відповіді повертається id та name збереженого документа.

curl -X POST 'https://kadry.vchasno.ua/api/public/v1/bulk-signing/9a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7a8b/document' \
  -H 'X-Vchasno-Public-Token: <ваш_токен>' \
  -F '[email protected]'

{
  "detail": {
    "id": "d1e2f3a4-5b6c-4d7e-8f90-1a2b3c4d5e6f",
    "name": "order-42.pdf"
  }
}

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

Ендпоінт POST /api/public/v1/bulk-signing/{task_id}/send. Тіло запиту не потрібне.

Надсилання асинхронне: запит одразу повертає задачу зі статусом sending та кодом 202 Accepted, а фактична відправка документів до ЕДО виконується у фоні. Поки задача в статусі sending, вона заблокована (повторне надсилання чи завантаження недоступні). Результат слід відстежувати через GET .../{task_id}, .../signers та .../signers/counts: після успішної відправки задача переходить у in_progress, а маршрут — у in_progress; у разі помилки маршрут переходить у error.

curl -X POST 'https://kadry.vchasno.ua/api/public/v1/bulk-signing/9a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7a8b/send' \
  -H 'X-Vchasno-Public-Token: <ваш_токен>'

{
  "detail": {
    "id": "9a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7a8b",
    "name": "Ознайомлення з наказом №42",
    "status": "sending",
    "end_date": "2026-08-15",
    "initiator_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "b2c3d4e5-6f70-4a1b-8c2d-3e4f5a6b7c8d"
    ]
  }
}

Перегляд задач¶

Список задач¶

Ендпоінт GET /api/public/v1/bulk-signing. Повертає посторінковий список задач масового підпису компанії. Тип задачі фіксується сервером, тому у вибірку потрапляють лише задачі масового підпису.

Корисні параметри фільтрації (query): status__in, initiator__in, search, external_id__in, date_created__gte / date_created__lte, date_updated__gte / date_updated__lte, а також пагінація (page, size). Наприклад, лише незавершені задачі:

curl 'https://kadry.vchasno.ua/api/public/v1/bulk-signing?status__in=new&status__in=in_progress&page=1&size=20' \
  -H 'X-Vchasno-Public-Token: <ваш_токен>'

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

Ендпоінт GET /api/public/v1/bulk-signing/{task_id}.

curl 'https://kadry.vchasno.ua/api/public/v1/bulk-signing/9a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7a8b' \
  -H 'X-Vchasno-Public-Token: <ваш_токен>'

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

Список підписантів-отримувачів¶

Ендпоінт GET /api/public/v1/bulk-signing/{task_id}/signers — посторінковий список отримувачів та їх статусів підписання.

Параметри фільтрації (query): status__in (за статусом підписанта), position__in, group__in, social_status_type__in, search, плюс пагінація. Наприклад, лише ті, хто ще не підписав:

curl 'https://kadry.vchasno.ua/api/public/v1/bulk-signing/9a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7a8b/signers?status__in=new' \
  -H 'X-Vchasno-Public-Token: <ваш_токен>'

Лічильники підписантів¶

Ендпоінт GET /api/public/v1/bulk-signing/{task_id}/signers/counts — зведені лічильники (скільки підписали, очікують, відхилили тощо). Приймає ті самі фільтри, що й список підписантів.

curl 'https://kadry.vchasno.ua/api/public/v1/bulk-signing/9a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7a8b/signers/counts' \
  -H 'X-Vchasno-Public-Token: <ваш_токен>'

{
  "detail": {
    "all": 120,
    "signed": 87,
    "awaiting": 30,
    "rejected": 2,
    "delete_requested": 1
  }
}

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

Нагадати одному підписанту¶

Ендпоінт POST /api/public/v1/bulk-signing/{task_id}/signer/{employee_id}/remind. Надсилає нагадування конкретному отримувачу, який ще не підписав. Діє обмеження частоти (як і для кнопки нагадування у вебінтерфейсі). Відповідь повертається без обгортки detail:

curl -X POST 'https://kadry.vchasno.ua/api/public/v1/bulk-signing/9a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7a8b/signer/3fa85f64-5717-4562-b3fc-2c963f66afa6/remind' \
  -H 'X-Vchasno-Public-Token: <ваш_токен>'

{ "status": true }

Нагадати всім, хто ще не підписав¶

Ендпоінт POST /api/public/v1/bulk-signing/{task_id}/signers/remind-all. Ставить нагадування в чергу для всіх отримувачів, які ще не підписали. Обробка асинхронна — відповідь лише підтверджує, що нагадування поставлені в чергу:

curl -X POST 'https://kadry.vchasno.ua/api/public/v1/bulk-signing/9a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7a8b/signers/remind-all' \
  -H 'X-Vchasno-Public-Token: <ваш_токен>'

{ "detail": { "enqueued": true } }

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

Відповіддю цих ендпоінтів є сам файл (attachment), а не JSON.

За ID документа¶

Ендпоінт GET /api/public/v1/bulk-signing/{task_id}/document/{document_id}/download. Значення document_id — це route_id конкретного підписанта зі списку .../signers.

curl 'https://kadry.vchasno.ua/api/public/v1/bulk-signing/9a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7a8b/document/7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f/download' \
  -H 'X-Vchasno-Public-Token: <ваш_токен>' \
  -o signed.pdf

За отримувачем¶

Ендпоінт GET /api/public/v1/bulk-signing/{task_id}/document/download?initiator_id=…. Зручний, коли ви знаєте лише ID отримувача, а не ID документа. Співробітник має бути отримувачем саме цієї задачі; якщо задачу ще не надіслано, повертається 404.

curl 'https://kadry.vchasno.ua/api/public/v1/bulk-signing/9a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7a8b/document/download?initiator_id=3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'X-Vchasno-Public-Token: <ваш_токен>' \
  -o signed.pdf

Завершення та скасування задачі¶

Завершити задачу¶

Ендпоінт POST /api/public/v1/bulk-signing/{task_id}/complete. Завершує задачу вручну. Спроба завершити вже завершену чи скасовану задачу поверне помилку.

curl -X POST 'https://kadry.vchasno.ua/api/public/v1/bulk-signing/9a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7a8b/complete' \
  -H 'X-Vchasno-Public-Token: <ваш_токен>'

Скасувати задачу¶

Ендпоінт POST /api/public/v1/bulk-signing/{task_id}/cancel. Потребує причини скасування (cancellation_reason, до 500 символів).

curl -X POST 'https://kadry.vchasno.ua/api/public/v1/bulk-signing/9a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7a8b/cancel' \
  -H 'X-Vchasno-Public-Token: <ваш_токен>' \
  -H 'Content-Type: application/json' \
  -d '{ "cancellation_reason": "Наказ відкликано" }'

Очікувана послідовність дій¶

1. Створити задачу «Масовий підпис», передавши назву та список отримувачів (initiator_ids).

2. Завантажити документ для підпису — цей крок одночасно будує маршрут підписання з отримувачів.

3. Надіслати документ на підпис отримувачам (асинхронно, задача переходить у sending).

4. Відстежувати статус задачі та лічильники підписантів, за потреби надсилати нагадування.

5. Завантажити підписані документи та, за потреби, завершити або скасувати задачу.

Приклади сценаріїв використання¶

• Ознайомлення з наказом. Створіть задачу з отримувачами-працівниками, завантажте PDF наказу, надішліть на підпис. Опитуйте .../signers/counts, поки signed не дорівнюватиме all; тим, хто зволікає, надсилайте .../remind-all.
• Періодичне ознайомлення з політиками (інтеграція з ERP). З боку ERP створюйте задачу масового підпису з актуальним списком співробітників за розкладом, зберігайте task_id, а статуси синхронізуйте через GET /bulk-signing/{task_id} і .../signers. Підписані файли для архіву забирайте через .../document/download?initiator_id=….
• Контроль відхилень. Відфільтруйте підписантів за status__in=declined, щоб отримати перелік тих, хто відхилив, разом із decline_reason, і обробіть їх окремо. Запити на видалення документа видно як status=delete_request та у лічильнику delete_requested.