WhiteDoc API. Відправка файлів за шаблоном

Схема інтеграції

1. Призначення методу

Відправка документів на основі вже існуючого шаблону (template) у WhiteDoc. Типовий сценарій — облікова система (наприклад, ERP) обробляє запит і формує на її основі документ (наприклад, акт виконаних робіт) і додає цей готовий файл до конверту, що створюється за шаблоном.

Процес складається з кроків:

1. Отримання/заповнення XML-конверту за шаблоном.

2. Завантаження сформованого файлу (наприклад, PDF наказу) на сервер WhiteDoc.
3. Додавання UUID вкладення у XML конверту.
4. Відправка конверту на підпис контрагенту.

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

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

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

Це дозволяє:

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

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

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

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

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

Посилання:

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

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

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

Authorization: Bearer API_TOKEN

3. Попередні умови

Для виконання запиту потрібен UUID mailbox 
https://help.whitedoc.ua/uk/mailbox/uuid-mailbox

Додатково потрібен UUID шаблону, за яким формується конверт (templateUuid), відомий заздалегідь зі сторінки шаблону в WhiteDoc.

3. Заповнення конверту за шаблоном

🔗 Swagger: розділ template-controller / envelope-controller (методи заповнення та створення конверту з шаблону — fillEnvelope / sendEnvelope)

На цьому кроці система клієнта передає у WhiteDoc XML із даними, які потрібно підставити у поля шаблону (аналогічно структурі полів <field name="...">).

⚠️ Точна структура запиту заповнення шаблону (список обов'язкових полів, формат templateUuid / templateVersion) залежить від конкретного шаблону — орієнтуватись на Swagger.

4. Завантаження файлу на сервер 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=@act.pdf"

Результат

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

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

json

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

5. Додавання 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:

• документ стає частиною конверту;
• WhiteDoc відправляє документ по налаштованому процесу

6. Відправка конверту

🔗 Swagger: envelope-controller/sendEnvelope

Метод: POST. Тіло запиту — заповнений XML конверту (з розділів 3 і 5), який передається на відправку. Заголовки — ті самі Authorization і Mailbox.

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

json

{
  "uuid": "6a9c4dd8-f1fd-426d-8b18-c894b85fb8a3",
  "status": "SENT",
  "created": "2026-08-17T10:00:00.000Z"
}

7. Подальше відстеження

Аналогічно базовому документу: статус конверту відстежується через callback або polling (searchEnvelopes), сам конверт отримується через getEnvelopeByUuid, а повний архів — через getEnvelopeZip.

8. Типові помилки