WhiteDoc API. Отримати документи та файли конверту, основні дії

1. Початок роботи 

1.1 Створення користувача 

У системі WhiteDoc необхідно створити окремого користувача, який буде використовуватись виключно для інтеграції. 

1.2 Створення API-токена 

Після створення користувача необхідно згенерувати API-токен: 

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

Результат: 

• API token використовується для авторизації всіх подальших API-запитів 

• Токен передається в Authorization header (Bearer token) 

---

 

2. Налаштування автоматичного callback (тригера) 

2.1 Створення callback 

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

2.2 HTTP-запит 

Метод: POST 

Headers:

Примітка щодо Mailbox: 

• Mailbox — це поштова скринька (етап процесу), на якій відслідковуються документи 

• Можна використовувати стандартні (наприклад, “Архів”) або створити окремий крок процесу 

2.3 Body (опис полів) 

2.4 Очікувана поведінка 

• WhiteDoc викликає ваш endpoint 

• У callback передається UUID конверту 

• Ваша система ініціює отримання XML 

2.1 Отримання конвертів без callback (періодичний пошук / polling) 

У випадках, коли використання callback неможливе (обмеження мережі, відсутність публічного endpoint, вимоги безпеки), система може використовувати періодичний пошук конвертів через API WhiteDoc. 

Коли використовувати polling замість callback 

• немає можливості приймати вхідні HTTP-запити 

• callback блокується firewall / VPN 

• потрібен повний контроль над частотою перевірок 

• інтеграція з legacy-системою 

 Endpoint пошуку конвертів

🔗 Swagger: 
https://api.whitedoc.ua/swagger-ui/index.html#/envelope-search-controller/searchEnvelopes 

 HTTP-запит

Метод: POST 

Headers: 

Параметри пошуку (body — логічний опис) 

Успішна відповідь містить: 

• список конвертів 

• їх UUID 

• базові метадані (статус, дати) 

Ці UUID використовуються для: 

• отримання XML (getEnvelopeByUuid) 

• отримання ZIP (getEnvelopeZip) 

• подальшої бізнес-обробки 

---

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

3.1 Запит отримання конверту 

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

Метод: GET 

Headers: 

Path параметри:

• uuid — UUID конверту, отриманий з callback 

3.2 Відповідь

1. XML-конверт з повною інформацією

2. Містить:

   1. uuid конверту

   2. document id

   3. метадані документа

   4. статуси та учасників 

<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?> 
<envelope templateUuid=\"0347c2e7-e850-49f0-bafc-645679d0fdd5\
" templateVersion=\"07748953-c95a-47c2-8856-4f56b787679b\
" created=\"2026-01-29T13:40:42.116Z\"> 
<state> 
<status>SENT</status> 
<date>2026-01-29T13:40:42.116Z</date> 
</state> 
<info> 
<subject>Видаткова накладна на повернення, 12, 29.01.2026</subject> 
<message></message> 
<forwarding delegation=\"true\" sharing=\"true\"/> 
</info> 
<documents> 
<document id=\"d1f1f655-5e52-413c-9255-f5f1f8910ea3\"> 
<field name=\"Дата одержання\">2026-01-29</field> 
<field name=\"Адреса\">Повна адреса</field> 
<field name=\"Номер документа\">12</field> 
<field name=\"Відвантажив. ПІБ\">ПІБ</field> 
<field name=\"МФО\">123456</field> 
<field name=\"Сума ПДВ\">800.00</field> 
<field name=\"IBAN\">UA1234567890123456</field> 
<field name=\"Телефон\">+380950000000</field> 
<field name=\"Постачальник\">ТОВ &quot;Постачальник&quot;</field> 
<field name=\"Свідоцтво\">АТ-01</field> 
<field name=\"QR штрихкод\">
https://edo.whitedoc.ua/envelope/view/6a9c4dd8-f1fd-426d-8b18-c894b85fb8a3
</field> 
<field name=\"Номер договору\">2025/01 - 1</field> 
<field name=\"Отримав. ПІБ\">ПІБ</field> 
<field name=\"Дата документа\">2026-01-29</field> 
<field name=\"ЄДРПОУ\">12345678</field> 
<field name=\"Покупець\">ТОВ &quot;Покупець&quot;</field> 
<field name=\"ІПН\">1234567890</field> 
<field name=\"Дата відвантаження\">2026-01-29</field> 
<field name=\"Найменування банку\">Банк</field> 
<field name=\"Разом без ПДВ\">4000.00</field> 
<field name=\"Разом з ПДВ\">4800.00</field> 
<fieldgroup name=\"Таблиця\"> 
<fieldset index=\"0\"> 
<field name=\"Найменування товару\">Найменування товару 1</field> 
<field name=\"Артикул\">123456</field> 
<field name=\"Кількість\">1</field> 
<field name=\"Ціна без ПДВ\">2000.00</field> 
<field name=\"Формула. Сума без ПДВ\">2000.00</field> 
</fieldset> 
<fieldset index=\"1\"> 
<field name=\"Найменування товару\">Найменування товару 2</field> 
<field name=\"Артикул\">123457</field> 
<field name=\"Кількість\">2</field> 
<field name=\"Ціна без ПДВ\">1000.00</field> 
<field name=\"Формула. Сума без ПДВ\">2000.00</field> 
</fieldset> 
</fieldgroup> 
</document> 
</documents> 
<flow> 
<roles> 
<role id=\"5f2944e1-7beb-4981-a3dc-c85d10559c91\
" mailboxUuid=\"8e716e7c-a10a-4699-ad0b-a972f7396e03\
" active=\"false\" completed=\"true\"/> 
<role id=\"5ad66714-eef1-4f0b-bd7b-7049b8ae283f\
" mailboxUuid=\"8e716e7c-a10a-4699-ad0b-a972f7396e03\
" active=\"true\" completed=\"false\"/> 
<role id=\"73ecc407-744c-42c5-b19f-782f1c3b4fa1\
" mailboxUuid=\"test@gmail.com\" active=\"false\
" completed=\"false\"/> 
</roles> 
</flow> 
</envelope>" 

---

4. Бізнес-перевірка даних 

На цьому етапі ваша система: 

• парсить XML 

• перевіряє коректність даних 

• приймає рішення: погодити або скасувати (якщо активний крок і не фінальний статус) 

---

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

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

• фіксації результатів перевірки 

• передачі службової інформації 

5.1 Створення коментар

🔗 Swagger: 
https://api.whitedoc.ua/swagger-ui/index.html#/envelope-controller/createEnvelopeComment 

Метод: POST 

Headers: 

5.2 Body (опис)

---

 

6. Погодження або скасування конверту 

6.1 Погодження 

🔗 Swagger: 
https://api.whitedoc.ua/swagger-ui/index.html#/envelope-controller/envelopeApproval 

Метод: POST 

Body:

• масив uuids конвертів 

• UUID береться із XML (<uuid>) або з Callback 

Результат: 

• Конверт переходить у погоджений статус 

 

6.2 Скасування 

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

Метод: POST 

Body: 

Результат:

• Конверт скасовується 

• Коментар зберігається в історії 

---

7. Отримання ZIP-архіву конверту 

Цей крок використовується, якщо необхідно завантажити конверт у вигляді ZIP-архіву, який зазвичай містить: 

• XML-документ 

• PDF / підписані файли 

• службові метадані (залежить від налаштувань WhiteDoc) 

7.1 Запит отримання ZIP-конверту 

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

7.2 HTTP-запит 

Метод: GET 

Headers: 

Path / Query параметри: 

• uuid — UUID конверту (отримується з callback або з XML) 

7.3 Відповідь 

Тип відповіді: 

• application/zip 

Результат: 

• ZIP-файл із повним вмістом конверту 

• Архів може бути збережений: 

• для локального зберігання 

• для передачі в іншу систему 

• для архівації або аудиту 

Типові помилки: