WhiteDoc API. Кадровий процес

Архітектура інтеграції кадрового процесу

Загальна схема взаємодії систем 

1. Загальна схема роботи кадрового процесу

WhiteDoc дозволяє автоматизувати кадрові процеси, такі як:

• заяви на відпустку

• заяви на відрядження

• погодження кадрових документів

• формування наказів.

Типовий процес виглядає так:

1. Співробітник створює кадрову заяву у WhiteDoc.

2. Дані можуть:

   • вводитись вручну

   • підставлятись із профілю або довідника.

3. Співробітник підписує документ КЕП / ЕЦП.

4. Документ переходить у workflow погодження.

5. Після підписання WhiteDoc надсилає callback у систему клієнта.

6. Система клієнта отримує UUID конверту.

7. Через API система отримує XML документу.

8. HR / ERP система:

   • обробляє дані

   • перевіряє ліміти

   • формує наказ.

9. Наказ завантажується назад у WhiteDoc.

10. Співробітник підписує наказ.

11. Процес завершується.

2. Початок роботи з API

2.1 Створення технічного користувача

Для інтеграції рекомендується створити окремого користувача, який буде використовуватись тільки для API інтеграції.

Це дозволяє:

• ізолювати інтеграційні доступи

• контролювати права

• безпечно керувати токенами.

2.2 Створення API токена

Token створюється у профілі користувача.

Посилання:

https://edo.whitedoc.ua/profile?activeTab=application-tokens

Токен використовується для авторизації усіх API запитів.

Header авторизації:

Authorization: Bearer API_TOKEN

3. Створення користувача (співробітника)

3.1 Самостійна реєстрація користувача

Співробітник може самостійно зареєструватися у системі WhiteDoc через форму реєстрації.

У цьому випадку користувач:

1. відкриває сторінку реєстрації

2. вводить email та інші необхідні дані

3. підтверджує реєстрацію.

Після реєстрації користувач може:

• входити у систему

• підписувати документи

• брати участь у workflow.

Цей підхід часто використовується у випадках, коли організація не має інтеграції з HR системою.

3.2 Імпорт користувачів через адміністративну панель

Адміністратор системи може масово створити користувачів, імпортувавши файл зі списком співробітників.

Зазвичай використовується файл формату:

CSV / XLSX

3.3 Створення користувача через API

Найбільш поширений варіант при інтеграції — автоматична синхронізація користувачів з HR / ERP системи.

У цьому випадку HR система виступає master-системою, а WhiteDoc отримує дані співробітників через API.

Це дозволяє:

• автоматично створювати нових співробітників

• оновлювати дані

• уникнути ручного введення.

Swagger endpoint:

https://api.whitedoc.ua/swagger-ui/index.html#/account-controller/createCorporateUser

Headers

Body

{
  "email": "user@example.com",
  "firstName": "string",
  "lastName": "string",
  "createMailbox": true,
  "phone": "stringst",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

CURL приклад

curl -X POST "https://api.whitedoc.ua/user-controller/createUser" \
-H "Authorization: Bearer API_TOKEN" \
-H "Mailbox: MAILBOX_UUID" \
-H "Content-Type: application/json" \
-d '{
  "email": "user@example.com",
  "firstName": "string",
  "lastName": "string",
  "createMailbox": true,
  "phone": "stringst",
  "fields": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}'

Обов’язкові поля

Додаткові поля (fields)

4. Налаштування callback

Callback дозволяє WhiteDoc повідомляти вашу систему про зміну статусу документа.

Наприклад:

• документ підписаний

• документ завершений

• документ на погодженні.

Swagger endpoint:

https://api.whitedoc.ua/swagger-ui/index.html#/envelope-callback-controller/createCallback

Headers

CURL приклад

curl -X POST "https://api.whitedoc.ua/envelope-callback-controller/createCallback" \
-H "Authorization: Bearer API_TOKEN" \
-H "Mailbox: MAILBOX_UUID" \
-H "Content-Type: application/json" \
-d '{
  "filter": {
    "status": ["COMPLETED"],
    "scope": ["inbox"]
  },
  "url": "https://client-system/api/callback",
  "retries": 3,
  "timeout": 5000,
  "successCode": 200,
  "login": "string",
  "password": "string",
}'

Коли статус документа змінюється, WhiteDoc викликає endpoint вашої системи.

5. Отримання XML конверту

Після отримання callback система повинна отримати XML документ, а також дані про envelope. В шаблоні WhiteDoc можуть бути декілька документів.

Swagger endpoint:

https://api.whitedoc.ua/swagger-ui/index.html#/envelope-controller/getEnvelopeByUuid

Headers

CURL приклад

curl -X GET \
"https://api.whitedoc.ua/envelope-controller/getEnvelopeByUuid/{uuid}" \
-H "Authorization: Bearer API_TOKEN" \
-H "Mailbox: MAILBOX_UUID"

6. Парсинг XML

Отриманий XML містить:

• поля документа

• метадані

• статуси.

Система повинна:

1. розпарсити XML

2. отримати поля

3. передати їх у HR систему.

Приклад структури:

<envelope templateUuid=\"d7b4fdf4-7194-4de6-86ef-d2598a64bfb1\" templateVersion=\"09541def-b4c7-42e7-aa83-31f439b358cb\">
	<info>
		<message/>
		<forwarding delegation=\"true\" sharing=\"true\"/>
	</info>
	<flow>
		<roles>
			<role id=\"64d77aca-f3b9-498d-93c8-830de40d4a5d\" mailboxUuid=\"d4b20877-3ad3-4420-9605-c1809a97fa46\"/>
			<role id=\"8d73bb83-a9b2-4f9d-9a6a-f789cde3fb62\"/>
			<role id=\"3bd7811d-5789-4d17-9761-cd4b81a47277\"/>
			<role id=\"5da19ab0-6760-4a86-97e7-ebc49548735c\"/>
		</roles>
	</flow>
	<documents>
		<document id=\"a280fcfd-54de-4c91-94a1-183f29a1d20a\">
			<field name=\"Найменування організації\"/>
			<field name=\"ПІБ директора\"/>
			<field name=\"Посада працівника\">Software Engineer</field>
			<field name=\"Підрозділ працівника\">Відділ розробки</field>
			<field name=\"ПІБ працівника\">Іваненко Іван Іванович</field>
			<field name=\"ПІБ працівника (Н.в.)\">Іваненко Іван Іванович</field>
			<field name=\"Кількість днів відпустки\">10</field>
			<field name=\"Дата початку відпустки\">2026-03-09</field>
			<field name=\"Дата заяви\"/>
			<field name=\"QR штрихкод 3\"/>
		</document>
	</documents>
</envelope>

7. Бізнес перевірка

Зазвичай цей етап відбувається під час погодження документа, коли він знаходиться на відповідному кроці workflow.

Для користувача цей процес виглядає наступним чином:

1. Користувач створює та підписує документ.

2. Документ переходить у статус “На погодженні”.

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

4. У цей момент інтегрована система клієнта отримує дані документа через API.

5. Система виконує необхідні бізнес-перевірки.

До таких перевірок можуть належати:

• перевірка залишку відпустки

• перевірка лімітів

• перевірка доступності співробітника

• перевірка коректності дат

• інші внутрішні правила компанії.

Після завершення перевірки система клієнта приймає рішення:

• погодити документ — якщо всі перевірки пройдені успішно

• скасувати документ — якщо перевірка не пройдена.

Якщо документ погоджується, WhiteDoc переводить його на наступний етап workflow.

У випадку кадрових процесів це може бути:

• етап формування наказу

• підпис керівника

• фінальне завершення процесу.

8. Додавання коментаря

Система може додати коментар до документа та повідомити користувача про результат бізнес перевірок. Коментарі супроводжуться сповіщеннями на email користувача.

Swagger endpoint:

https://api.whitedoc.ua/swagger-ui/index.html#/envelope-controller/getEnvelopeComments

Headers

CURL приклад

curl -X POST "https://api.whitedoc.ua/envelope-controller/createEnvelopeComment" \
-H "Authorization: Bearer API_TOKEN" \
-H "Mailbox: MAILBOX_UUID" \
-H "Content-Type: application/json" \
-d '{
  "documentId": "string",
  "text": "string",
  "accessType": "mailbox"
}'

9. Погодження документа

Система погоджує документ і переводить на наступний етап в процесі

Swagger endpoint:

https://api.whitedoc.ua/swagger-ui/index.html#/envelope-controller/approve

Headers

CURL приклад

curl -X POST "https://api.whitedoc.ua/envelope-controller/envelopeApproval" \
-H "Authorization: Bearer API_TOKEN" \
-H "Mailbox: MAILBOX_UUID" \
-H "Content-Type: application/json" \
-d '{
 "uuids": ["uuid"]
}'

10. Скасування документа

Swagger endpoint:

https://api.whitedoc.ua/swagger-ui/index.html#/envelope-controller/cancelEnvelopes

Headers

CURL приклад

curl -X POST "https://api.whitedoc.ua/envelope-controller/cancelEnvelopes" \
-H "Authorization: Bearer API_TOKEN" \
-H "Mailbox: MAILBOX_UUID" \
-H "Content-Type: application/json" \
-d '{
 "uuids": ["uuid"],
 "comment": "Rejected"
}'

11. Повернення сформованого наказу у WhiteDoc

Після обробки заяви HR система клієнта може сформувати наказ або інший службовий документ (наприклад: наказ про відпустку). Дані XML дозволяють отримати всі необхідні дані для формування наступних документів.

Щоб додати цей документ до процесу у WhiteDoc, необхідно виконати два кроки:

1. Завантажити файл наказу на сервер WhiteDoc

2. Додати UUID вкладення у XML конверту

Після цього документ стає частиною конверту і може бути відправлений на підпис співробітнику.

11.1. Завантаження файлу на сервер WhiteDoc

На цьому етапі система клієнта завантажує файл (наприклад PDF наказу) у файлове сховище WhiteDoc.

У відповідь API повертає UUID вкладення, який буде використаний у наступному кроці.

Swagger endpoint:

https://api.whitedoc.ua/swagger-ui/index.html#/envelope-controller/createAttachment

Headers

Формат запиту

Файл передається як multipart/form-data.

CURL приклад

curl -X POST "https://api.whitedoc.ua/attachment-controller/upload" \
-H "Authorization: Bearer API_TOKEN" \
-H "Mailbox: MAILBOX_UUID" \
-F "file=@order.pdf"

Приклад відповіді

{
  "uuid": "4a3d1f1a-1a6e-4f5a-9d3c-91b20a8d0e3d",
  "name": "order.pdf",
  "size": 248392
}

Результат

Система клієнта отримує:

attachment_uuid

Цей UUID використовується для додавання файлу до XML конверту.

11.2. Додавання UUID вкладення у XML конверту

Після завантаження файлу необхідно додати вкладення до конверту.

Це робиться шляхом додавання UUID attachment у XML структуру документа.

Після цього файл стає частиною конверту.

		<document id=\"8194259e-5021-425e-9016-38b7e40975d2\">
			<field name=\"dc8494f1-9360-4cb7-bd32-d67b831e08d7\" attachmentUuid=\"4a3d1f1a-1a6e-4f5a-9d3c-91b20a8d0e3d\">order.pdf</field>
		</document>

Що відбувається після додавання attachment

Після того як attachment доданий у XML:

1. документ стає частиною конверту

2. його можна включити у workflow

3. WhiteDoc відправляє документ на підпис співробітнику.

12. Отримання ZIP архіву

Можна отримати всі файли конверту, а також підписів.

Swagger endpoint:

https://api.whitedoc.ua/swagger-ui/index.html#/envelope-controller/getEnvelopeZip

Headers

CURL приклад

curl -X GET \
"https://api.whitedoc.ua/envelope-controller/getEnvelopeZip/{uuid}" \
-H "Authorization: Bearer API_TOKEN" \
-H "Mailbox: MAILBOX_UUID" \
--output envelope.zip

12. Рекомендації

Retry стратегія

При інтеграції рекомендується повторювати запити у випадку помилок.

Idempotency

Callback може приходити кілька разів.

Тому рекомендується перевіряти:

envelope_uuid

щоб уникнути повторної обробки.

Logging

Рекомендується логувати:

• callback received

• xml downloaded

• xml parsed

• order generated

• attachment uploaded