API Вчасно
Принцип роботи
Робота з API відбувається по протоколу HTTPS, де рішення, перевіряти чи не
перевіряти сертифікати приймає клієнт. У свою чергу ми будемо намагатись завжди
мати валідні HTTPS-сертифікати.
У системі "Вчасно" діють обмеження на завантаження файлів:
- Одне завантаження не повинно містити більше, ніж 500 файлів, сумарним
розміром не більше 100 Мб.
- Вага одного файла не повинна перевищувати 5 Мб.
Авторизація
Авторизація з API відбувається за допомогою передачі заголовку Authorization при
кожному запиті даних:
1. Authorization: <token>, де <token> – унікальний токен, котрий надаєтся системою
для зв'язки користувач+компанія
Як створити токен користувача “Вчасно”
2. content-type: application/json (для завантаження документу content-type:
multipart/form-data)
Типи параметрів
- str - будь-який рядок; якщо тип параметру не вказано, то мається на увазі саме цей
тип
- datetime - рядок у форматі YYYY-MM-DD (наприклад 2019-10-11) або
YYYY-MM-DDTHH:MM (наприклад 2019-10-11T11:12)
Ліміти по запитам
Обмеження кількості запитів від однієї компанії:
● загальне - 500 запитів/60 секунд;
Активація тестового тарифу Інтеграція
Формат запиту
POST /api/v2/billing/companies/rates/trials
{
"rate": "integration_trial"
}
Статус:
- 201 - успішно активовано тестовий тариф Інтеграція на 30 днів
Тестовий тариф може бути активований для компанії один раз.
Отримання статусів вихідних документів
Формат запиту
GET /api/v2/documents
Вивантаження статусів відбувається по GET запиту до URL /api/v2/documents
Підтримуються наступні параметри запиту:
- date_from (datetime) - повертаються документи із датою завантаження більшою або
рівною за вказану;
- date_to (datetime) - повертаються документи із датою завантаження меншою або
рівною за вказану;
- date_rejected_from (datetime) - повертаються документи із датою відхилення більшою
або рівною за вказану;
- date_rejected_to (datetime) - повертаються документи із датою відхилення меншою
або рівною за вказану;
- date_document_from (datetime) - повертаються документи із датою документу
більшою або рівною за вказану;
- date_document_to (datetime) - повертаються документи із датою документу меншою
або рівною за вказану;
- date_finished_from (datetime) - повертаються документи із датою завершення
документу більшою або рівною за вказану;
- date_finished_to (datetime) - повертаються документи із датою завершення документу
меншою або рівною за вказану;
- extension - формат завантаженого документу (наприклад .xml);
- recipient_edrpou - ЄДРПОУ отримувача документу;
- number - номер документа;
- status - код статусу документа;
- category - тип документу у системі "Вчасно";
- vendor - значення, якою інтеграцією був завантажений документ;
- vendor_id - ІД документа у системі вендора (клієнта);
- cursor - токен пагінації; значення, отримане із поля "next_cursor" відповіді на
попередній запит. Використовується для отримання наступної партії документів;
- ids - id документа; цей параметр можна повторювати багато разів для повернення
статусів документів за переліком ID;
- has_changed (bool) - з моменту останнього запиту була здійснена одна чи більше дій
над документом (завантаження, коментар, підписання, відправлення, відхилення).
Після запиту статус has_changed змінюється на False.
Приклад запиту: ?has_changed=1;
- is_delivered (bool) - документ отримано в сервісі Вчасно;
- with_tags (bool) - отримувати список ярликів документу;
- tag_id (str) - ID ярлика, що був присвоєний документу;
- not_tagged (bool) - отримати документи без присвоєних ярликів;
- with_recipients (bool) - у відповіді додається інформація про ЄДРПОУ, email
співробітника, що завантажив документ та назву компанії відправника документу, та
інформація про ЄДРПОУ, email та назву компанії отримувача документу;
- with_connections (bool) - у відповіді додається інформація про основний та дочірній
документи;
- amount_eq - повертаються документи із сумою рівною за вказану (ціле число в
копійках). Фільтр ігнорує інші фільтри суми;
- amount_gte - повертаються документи із сумою більшою або рівною за вказану;
- amount_lte - повертаються документи із сумою меншою або рівною за вказану;
- with_document_fields (bool) - у відповіді додається інформація по додаткових
параметрах документу;
- with_versions (bool) - у відповідь додається інформація про версії документа.
Формат відповідей
Наразі кожний документ, котрий завантажений у сервіс, можна представити
за допомогою наступного JSON:
documents:
{
"id": str,
"vendor": str,
"vendor_id": str,
"status": int,
"signatures_to_finish": int,
"first_sign_by": "owner" | "recipient",
"extension": str,
"signatures": [
{
"id": str,
"email": str,
"date_created": str
}
],
"title": str,
"type": str | null,
"amount": int | null,
"date": str | null,
"date_created": str,
"date_finished": str | null,
"date_delivered":str | null,
"number": str | null,
"preview_url": str | null,
"url": str,
"is_multilateral": true,
"category": int,
"is_delivered": bool,
}
"next_cursor": str | null
де:
- id - внутрішній ІД документа у системі "Вчасно";
- vendor - значення, якою інтеграцією був завантажений документ – в нашому випадку
тут завжди буде значення "API";
- vendor_id - ІД документа у системі вендора (клієнта);
- status - статус документа у системі "Вчасно";
- signatures_to_finish - кількість підписів, після котрих документ буде визнано
завершеним (для рахунків: 1, для актів та інших документів: 2 і більше);
- first_sign_by - сторона яка перша накладає підпис;
- extension - розширення документа;
- signatures - накладені підписи:
- id - id підпису;
- email - email співробітника, що підписав документ;
- date_created - дата підписання згідно стандарту ISO 8601;
- title - назва документу;
- type - назва (тип) документу (довільний), наприклад "Реалізація товарів і послуг".
Може бути null.
- amount - сума документу (ціле число в копійках);
- category - тип документу у системі "Вчасно";
- date - дата документу згідно стандарту ISO 8601;
- date_created - дата завантаження документу згідно стандарту ISO 8601;
- date_delivered - дата отримання документу згідно стандарту ISO 8601;
- date_finished - дата завершення документу згідно стандарту ISO 8601;
- number - зовнішній номер документу;
- preview_url - якщо не null, то це сторінка перегляду документу в сервісі Вчасно.
*Доступ до такої сторінки можливий без логіну та паролю;
- url - сторінка документу в сервісі “Вчасно”;
- is_multilateral - ознака багатостороннього документу;
- is_delivered - документ отримано в сервісі “Вчасно”;
- next_cursor:
-якщо не null, то це значення можна передати як параметр “cursor” для
отримання наступної партії документів;
-якщо null, то це остання партія документів, які відповідають параметрам запиту.
Значення поля "Статус":
- 7000 - документ завантажений у систему;
- 7001 - документ готовий для підпису і надсилання (вказані дані контрагента);
- 7002 - документ надісланий контрагенту на перший підпис;
- 7003 - документ підписаний не всіма підписами, що необхідні зі сторони власника
документу, або не надісланий після підписання;
- 7004 - документ підписаний власником, та очікує на підпис контрагента;
- 7006 - документ відхилений контрагентом;
- 7007 - документ підписаний не всіма підписами, що необхідні зі сторони отримувача
документу, або не надісланий після підписання;
- 7008 - на документ накладено всі очікувані підписи;
- 7010 - документ надісланий підписантам (для багатостороннього документу).
Значення поля "Тип" (category):
- 0 - тип не обрано
- 1 - акт наданих послуг
- 2 - рахунок
- 3 - договір
- 4 - додаткова угода до договору
- 5 - видаткова накладна
- 6 - товарно-транспортна накладна
- 7 - EDI документи
- 8 - довіреність
- 9 - специфікація
- 10 - заява
- 11 - акт приймання-передачі
- 12 - повернення
- 13 - замовлення
- 14 - додаток
- 15 - інше
- 16 - акт звіряння
- 17 - протокол розбіжностей
- 18 - звіт
- 19 - лист
- 20 - протокол
- 21 - наказ
- 22 - акт повернення
- 23 - розрахунок коригування
- 24 - акт коригування
- 25 - гарантійний лист
-
26 - бухгалтерська довідка
27 - акт списання
28 - коригуюча накладна
29 - авансовий звіт
30 - акт інвентаризації
Значення "has_changed":
- "1" - з моменту останнього запиту була здійснена одна чи більше дій над документом
(завантаження, коментар, підписання, відправлення, відхилення);
- "0" - над документом не здійснювалася ні одна з дій, перерахованих вище, з моменту
останнього запиту.
Значення "is_delivered":
- "1" - проставляється якщо будь-який користувач, що має доступ до ЄДРПОУ
отримувача виконав одну з наступних дій: або увійшов у систему і побачив
перелік документів, або не виходячи з системи переключився на цю компанію,
або перебуваючи в компанії не виходив із системи і оновив сторінку із переліком
документів;
- "0" - над документом не здійснювалася ні одна з дій, перерахованих вище.
*Застаріла версія API за адресою /api/v1/documents відрізняється відсутністю
параметру cursor та поля next_cursor.
Значення "date_finished" (дата завершення документа):
У дату завершення документу проставляється дата, коли документ перейшов у статуси
7006, 7008. Якщо на документ у статусі 7008 додається додатковий підпис date_finished оновлюється датою додавання цього підпису.
Завантаження документів
Формат запиту
POST /api/v2/documents
Формат назви файлів
Для спрощення роботи у сервісі "Вчасно" і автоматичного представлення даних про
контрагентів та документ, прийнятий наступний формат назви файлів:
- <edrpou_owner>_<edrpou_recipient>_< ber>.pdf
- <edrpou_owner>_<edrpou_recipient>_<date>_<title>_<number>_<email_recipient>.pdf
- <edrpou_owner>_<edrpou_recipient>_<date>_<title>_<number>_<email_recipient>_<ve
ndor_id>.pdf
- <edrpou_owner>_<edrpou_recipient>_<date>_<title>_<number>_<email_recipient>_<ve
ndor_id>_<amount>.pdf
Де:
- <edrpou_owner> – ЄДРПОУ/ІПН власника документу*;
- <edrpou_recipient> – ЄДРПОУ/ІПН отримувача документу/контрагента;
або, якщо параметр is_internal = 1, то ЄДРПОУ/ІПН власника
- <date> – дата формування документу у форматі YYYYMMDD;
- <title> – назва документу;
- <number> – порядковий номер документу;
- <email_recipient> (необов’язково**) - email отримувача/контрагента документа;
- <vendor_id> (необов’язково) - ID документа за яким можна синхронізувати статуси
документів із відправником (власником);
- <amount> (необов’язково) - сума документу (ціле число в копійках);
* якщо параметр first_sign_by=recipient, edrpou_owner та edrpou_recipient
змінюються місцями.
** через кому без пробілів, при передачі декількох адрес. При завантаженні
документа з вказаним email отримувача, він автоматично отримує статус 7001
“Готовий до підпису та надсилання”, якщо email не передавався у назві - статус
7000 “Завантажений”, якщо контрагент не доданий до контактів компанії як
головний контакт.
Приклад назви документа:
2893102110_3235608644_20170213_РахунокНаОплатуПокупцю_Sch-025_tamara@vcha
sno.ua_d33d73c8-8784-18e8-8786-d43d7eaa0aae_10000.pdf
*Можливе завантаження архіва .zip, що містить до 500 таких документів.
Після надсилання у "Вчасно" файла з таким іменем, всі мета-дані про документ будуть
автоматично заповнені. Метадані можна передавати як іменем файлу, так і
параметрами, описаними нижче. В разі використання параметрів запиту - ім'я файлу
може бути довільним.
Необов’язкові параметри:
- expected_owner_signatures - (int) [ 0, 1, 2, 3 … ] - кількість необхідних підписів
власника (за замовчуванням = 1);
- expected_recipient_signatures - (int) [ 0, 1, 2, 3 … ] - кількість необхідних підписів
контрагента (за замовчуванням = 1);
- first_sign_by - (string) [‘owner’, ‘recipient’] сторона яка перша накладає підпис на
документ (за замовчуванням = ‘owner’);
- signer_roles - (string) ID ролі користувача-підписанта зі сторони відправника (id
користувача в певній компанії)*;
- signer_emails - (string) email користувача-підписанта зі сторони відправника*;
- parallel_signing - (bool) [true, false] - паралельне чи почергове підписання
користувачами (за замовчуванням = true);
- is_internal - (int) [ 0, 1 ] чи є внутрішнім документом, не потребує вказання ЕГРПОУ
та email отримувача (за замовчуванням = 0);
- is_multilateral - (bool) [true, false] - багатосторонній документ (не може
використовуватися із параметрами вказаними вище);
- is_parallel - (bool) [true, false] - паралельне чи почергове підписання
багатостороннього документа (за замовчуванням = true);
- share_to - (string) ID ролі користувача - відкриття доступу співробітнику до
документу*;
- reviewers_ids - (string) ID ролі користувача - додавання співробітника до
внутрішнього погодження*;
- parallel_review - (bool) [true, false] - паралельне чи почергове погодження (за
замовчуванням = true);
- is_required_review - (bool) [true, false] - заборонити підписувати або відхиляти, поки
документ не погоджено (за замовчуванням = false);
- tags - (string) ID ярлика, який буде присвоєний документу*;
- parent_id - (string) ID документу, якому буде завантажений поточний як дочірній;
- category - (int) ID типу документу (за замовчуванням = 0):
- 0 - Тип не обрано
- 1 - Акт наданих послуг
- 2 - Рахунок,
- 3 - Договір
- 4 - Додаткова угода до договору
- 5 - Видаткова накладна
- 6 - ТТН
- 7 - ЕДІ документи
- 8 - Довіреність
- 9 - Специфікація
- 10 - Заява
- 11 - Акт приймання-передачі
- 12 - Повернення
- 13 - Замовлення
- 14 - Додаток
- 15 - Інший
- 16 - Акт звіряння
- 17 - Протокол розбіжностей
- 18 - Звіт
- 19 - Лист
- 20 - Протокол
- 21 - Наказ
- 22 - Акт повернення
- 23 - Розрахунок коригування
- 24 - Акт коригування
- 25 - Гарантійний лист
- 26 - Бухгалтерська довідка
- 27 - Акт списання
- 28 - Коригуюча накладна
- 29 - Авансовий звіт
- 30 - Акт інвентаризації
- amount - сума документа (ціле число в копійках);
- title - назва документа;
-
doc_number - зовнішній номер документа;
date_document - дата формування документа (у форматі datetime);
recipient_edrpou - ЄДРПОУ/ІПН контрагента;
recipient_emails - Email контрагента*;
is_versioned - (bool) [true, false] - версійний документ;
template_id (string) - ID сценарію, який буде накладений на документ.
* - параметр може повторюватися багато разів.
Важливо:
У запиті потрібно використовувати визначення користувача-підписанта АБО за ID ролі,
АБО за email.
Заголовок запиту повинен містити рядок content-type: multipart/form-data.
Вказання підписантів багатостороннього
документа
Формат запиту
POST /api/v2/documents/{document_id}/flow
[
{
"edrpou": str,
"emails": [str],
"order": int,
"sign_num": int
},
{
"edrpou": str,
"emails": [str],
"order": int,
"sign_num": int
}
]
Де,
document_id - ID документа у сервісі ВЧАСНО
edrpou - ЄДРПОУ компанії підписанта
emails - email підписанта
order - черга у разі почергового підписання (починаючи з 0)
Для почергового підписання, документ потрібно завантажувати із GET-параметром
is_parallel=false
sign_num - кількість необхідних підписів
Увага! Одразу, після редагування підписантів, документ автоматично переходить у
статус підписання 7010.
Отримання вхідних документів
Формат запиту
GET /api/v2/incoming-documents
Підтримуються наступні параметри запиту:
- date_created_from (datetime) - повертаються документи із датою створення
(завантаження до Вчасно) більшою або рівною за вказану;
- date_created_to (datetime) - повертаються документи із датою створення
(завантаження до Вчасно) меншою або рівною за вказану;
- date_sent_from (datetime) - повертаються документи із датою надсилання більшою
або рівною за вказану;
- date_sent_to (datetime) - повертаються документи із датою надсилання меншою або
рівною за вказану;
- date_document_from (datetime) - повертаються документи із датою документу (з
параметру date) більшою або рівною за вказану. Якщо date=null - відбір не
відбувається;
- date_document_to (datetime) - повертаються документи із датою документу меншою
або рівною за вказану. Якщо date=null - відбір не відбувається;
- date_finished_from (datetime) - повертаються документи із датою завершення
документу більшою або рівною за вказану;
- date_finished_to (datetime) - повертаються документи із датою завершення документу
меншою або рівною за вказану;
- status - статус документу у системі "Вчасно";
- edrpou_owner - ЄДРПОУ/ІПН контрагента (відправника) документа;
- extension - формат завантаженого документу (наприклад .xml);
- category - тип документу у системі "Вчасно";
- cursor - токен пагінації; значення, отримане із поля "next_cursor" відповіді на
попередній запит. Використовується для отримання наступної партії документів;
- ids - id документа; цей параметр може повторюватися багато разів для повернення
статусів документів за переліком ID;
- with_recipients (bool) - у відповіді додається інформація про ЄДРПОУ, email та назву
компаній відправника та отримувача документа;
- with_connections (bool) - у відповіді додається інформація про основний та дочірній
документи;
- tag_id (str) - ID ярлика, що був присвоєний документу;
- not_tagged (bool) - отримати документи без присвоєних ярликів;
- amount_eq - повертаються документи із сумою рівною за вказану (ціле число в
копійках). Фільтр ігнорує інші фільтри суми;
- amount_gte - повертаються документи із сумою більшою або рівною за вказану;
- amount_lte - повертаються документи із сумою меншою або рівною за вказану;
- with_document_fields (bool) - у відповіді додається інформація по додаткових
параметрах документу;
- with_versions (bool) - у відповідь додається інформація про версії документа;
- processed (bool) - виводити тільки документи, які позначені (true)\не позначені (false) як
оброблені. Позначення відбувається за допомогою методу для обробки документів.
Формат відповіді
{
"documents": [
{
"id": str,
"extension": str,
"title": str,
"type": str | null,
"number": str | null,
"status": int,
"edrpou_owner": str,
"amount": int | null,
"company_name": str,
"signatures_to_finish": int,
"first_sign_by": "owner" | "recipient",
"date": str | null,
"date_created": str,
"date_delivered": str,
"date_finished": str | null,
"is_delivered": bool,
“category”: int,
"signatures": null,
"preview_url": str,
"url": str,
"parent": str | null,
"children": [str | null],
"recipients": [
{"edrpou": str,
"emails": [str],
"name": str,
"is_emails_hidden": bool}],
"fields": [{
"field_id": str,
"name": str,
"type": str,
"is_required": bool,
"value": str,
"date_updated": str,
"date_created": str}],
"versions": [{
"id": str,
"name": str,
"role_id": str,
"date_created": str,
"is_sent": bool,
"extension": str}],
"is_multilateral": bool,
}
],
"next_cursor": str | null
}
де:
- id - внутрішній ІД документа у системі "Вчасно";
- edrpou_owner - ЄДРПОУ власника документа;
- company_name - назва компанії власника документа;
- status - статус документа в системі "Вчасно";
- signatures_to_finish - кількість підписів, після котрих документ буде визнано
завершеним (для рахунка: 1, для актов/інших документів: 2+);
- first_sign_by - сторона яка перша накладує підпис на документ;
- extension - розширення документа;
- title - назва документа;
- type - тип документа, наприклад "РеализацияТоваровУслуг". Може бути null;
- category - тип документа у системі "Вчасно";
- number - зовнішній номер документу;
- date - дата документа згідно стандарту ISO 8601
- amount - сума документу;
- date_created - дата завантаження документу згідно стандарту ISO 8601
- date_delivered - дата отримання документу згідно стандарту ISO 8601
- date_finished - дата завершення документу згідно стандарту ISO 8601:
● у дату завершення документу проставляється дата, коли документ перейшов у
статуси 7006, 7008. Якщо на документ у статусі 7008 додається додатковий
підпис - date_finished оновлюється датою додавання цього підпису.
- is_delivered - документ отримано в сервісі “Вчасно”;
- preview_url - якщо не null, то це сторінка перегляду документу в сервісі Вчасно.
*Доступ до такої сторінки можливий без логіну та паролю;
- url - сторінка документу в сервісі “Вчасно”;
- parent, children - інформація по дочірнім документам, при використанні параметру
“with_connections”;
- recipients - інформація по відправнику та отримувачу документу, при використанні
параметру “with_recipients”;
- fields - інформація по додаткових параметрах документу, при використанні параметру
“with_document_fields”;
- is_multilateral - відмітка багатостороннього документу;
- next_cursor:
- якщо не null, то це значення можна передати як параметр cursor для
отримання наступної партії документів;
- якщо null, то це остання партія документів, які відповідають параметрам
запиту.
Застаріла версія API за адресою /api/v1/incoming-documents відрізняється
відсутністю параметру cursor та поля next_cursor.
Редагування підписантів документа
Формат запиту
POST /api/v2/documents/{document_id}/signers
{
"signer_entities": [
{
"type": "role",
"id": "<role_id>"
},
{
"type": "group",
"id": "<group_id>"
}
]
"is_parallel": false
}
Де,
document_id - ID документа у сервісі ВЧАСНО
signer_entities - масив з елементами:
type - приймає значення role або group
id - ID ролі або групи, яку потрібно додати до підписання
is_parallel - параметр, що відповідає за паралельне та почергове підписання. true підписати може кожен у будь-який час, false - підписання можливо тільки в такій
послідовності як у списку id.
roles - список id ролей підписантів виду ["role1_id", "role2_id", …] (параметр
застарілий, але ще підтримується)
Завантаження оригіналу документа
Формат запиту
GET /api/v2/documents/<document_id>/original
Підтримуються наступні параметри запиту:
- version - id версії документа для завантаження, або latest для завантаження
останньої версії.
Завантаження ZIP архіву із документом і
підписами
Формат запиту
GET /api/v2/documents/<document_id>/archive
Необов’язкові параметри:
- with_instruction (bool) - чи додавати інструкцію в архів.
якщо параметр дорівнює 1, то архів буде містити PDF файл з
інструкцією, як перевіряти документи на ЦЗО, якщо параметр дорівнює 0,
то архів не буде містити інструкції (за замовчуванням = 1)
- with_xml_preview (bool) - чи вивантажувати в архів візуалізацію XML.
- якщо параметр дорівнює 1, то архів буде містити PDF файл друкованої
форми XML документу, якщо параметр дорівнює 0, то архів не буде
містити файлу (за замовчуванням = 1).
- convert_to_signature_format - (str) - конвертувати підписи у певний формат під
час вивантаження.
Наразі параметр приймає лише одне значення - internal_appended
(підписи і оригінал в одному файлі). Допустимі варіанти підписів, які
можна конвертувати в цей формат: internal_separated, external_separated.
Завантаження ASIC контейнера з документом і
Євро-підписами
Метод для вивантаження євро-підписів документа (якщо такі накладені) у ASIC
контейнері
Формат запиту
GET /api/v2/documents/<document_id>/asic
Отримання документів для завантаження
Формат запиту
GET /api/v2/download-documents
Очікуються наступні параметри запиту:
- ids - id документа, може повторюватися багато разів для отримання декількох
документів для завантаження за переліком.
Формат відповіді
documents:
{
"archive_url": str,
"extension": str,
"id": str,
"original_url": str,
"xml-to-pdf_url": optional[str],
"status": "pending" | "ready"
}
"pending": int,
"ready": int,
"status": "empty" | "pending" | "ready",
"total": int
де:
archive_url - посилання на завантаження архіва з оригіналом і підписами;
extension - розширення файла;
original_url - посилання на вихідний файл;
xml-to-pdf_url - посилання на згенероване pdf відображення (тільки для xml
документу).
Завантаження PDF відображення XML
документу
1) Створити запит на формування:
Формат запиту
POST /api/v2/documents/<document_id>/xml-to-pdf
{
"force": bool
}
де:
document_id - документ для формування PDF;
force - створити PDF заново:
- true - використовується для візуалізації документа в новому (наступному) статусі;
- false - залишити існуючий PDF файл без змін.
2) Отримати сформований файл:
Формат запиту
GET /api/v2/documents/<document_id>/xml-to-pdf
Завантаження відображення PDF документу
Формат запиту
GET /api/v2/documents/<document_id>/pdf/print
де:
document_id - PDF документ для формування відображення.
Видалення документів
Видалення документа
Формат запиту
DELETE /api/v2/documents/<document_id>
Видаляти може лише компанія власник і роль, що має право на видалення
Зовнішні документи у статусі 7008 (підписаний всіма сторонами) видалити можливо
запитом на видалення до контрагента.
Створення запиту на видалення документів
Формат запиту
POST /api/v2/documents/<document_id>/delete-requests
{
“message”: str
}
message - текст який буде відображатись як причина запиту на видалення.
Створювати запит на видалення документу можуть лише компанії
власник/отримувач і ролі, що є адміністраторами та мають право на видалення.
Формат відповіді
Статус:
- 200 - запит успішний;
[
{
“id”: str,
“document_id”: str,
“message”: str,
“initiator_role_id”: str,
“reject_message”: null,
“receiver_edrpou”: str,
“status”: “new”,
“date_created”: datetime,
“date_accepted”: null,
“date_rejected”: null,
"cursor": str
}
]
Статус:
- 403 - немає доступу до самого документа, або немає прав на видалення.
Відміна запиту на видалення документів
Формат запиту
DELETE /api/v2/documents/<document_id>/delete-requests
Відмінити запит на видалення може лише роль яка створювала даний запит на
видалення і на даний момент має доступ до документу.
Статус:
- 200 - запит успішний
- 403 - немає доступу до самого документу або немає прав на видалення
Прийняття запиту на видалення документів
Формат запиту
POST /api/v2/documents/<document_id>/delete-requests/acceptions
Приймати запит на видалення може лише адміністратор компанії з доступом до
документу з правами на видалення документів.
Формат відповіді
Статус:
- 200 - запит успішний
- 403 - немає доступу до самого документу або немає прав на видалення
Відхилення запиту на видалення документів
Формат запиту
POST /api/v2/documents/<document_id>/delete-requests/rejections
{
“reject_message”: string,
}
reject_message - текст який буде відображатись як причина відхилення запиту
Відхиляти запит на видалення може лише адміністратор компанії з доступом до
документу з правами на видалення документів.
Формат відповіді
Статус:
- 200 - запит успішний
- 403 - немає доступу до самого документу або немає прав на видалення
Отримання списку запитів на видалення
документів компанії
Формат запиту
GET /api/v2/documents/delete-requests
Не обов’язкові GET параметри:
- status - статус запиту на видалення (new - новий, rejected - відхилений
отримувачем, canceled - відмінений відправником, accepted - прийнятий
отримувачем;
- ids - ID запиту на видалення документа;
- with_outgoing - true - отримати вхідні та вихідні запити, false - отримати лише вхідні
запити на видалення (за замовчуванням = true);
- cursor - токен пагінації; отриманий з мінімального курсору із попередньої вибірки в
100 шт. поля "cursor" відповіді на попередній запит. Використовується для отримання
наступної партії в 100 шт. запитів.
Формат відповіді
Статус:
- 200 - запит успішний;
[
{
“id”: str,
“document_id”: str,
“message”: str,
“initiator_role_id”: str,
“reject_message”: str | null,
“receiver_edrpou”: str,
“status”: “new” | “rejected” | “canceled” | “accepted”,
“date_created”: datetime,
“date_accepted”: datetime | null,
“date_rejected”: datetime | null,
"cursor": str
}
]
Позначити документ як оброблений
Формат запиту
POST /api/v2/documents/mark-as-processed
{
"document_ids": [
"doc_id1",
"doc_id2",
…
]
}
де
document_ids - масив з ID документів, які необхідно помітити як оброблені.
Формат відповіді
Статус:
- 200 - OK;
{
"updated_ids": [
str
]
}
Логіка роботи
Запит проставляє на документах processed=true.
Помітка автоматично знімається з документу (переходить в processed=false) у
наступних випадках:
● компанія-відправник документу змінила email отримувача документу;
● компанія-відправник документу додала новий підпис до документу.
Ярлики
Ярлики - це мітки у системі за допомогою яких можна помічати документи, а також
надавати доступ до документів. Кожен ярлик має бути прив’язаним хоча б до одного
документу або одного співробітника у системі. Адміністратори компанії мають доступ
до всіх ярликів у системі, інші користувачі лише до тих, які вони самі створили або до
яких адміністратор компанії надав доступ. Варто зазначити, що при присвоєнні ярлика
документу до якого користувач має доступ, користувач автоматично отримує доступ до
цього документу.
Створення нового ярлика і присвоєння
документу
Формат запиту
POST /api/v2/tags/documents
{
"documents_ids": [str, ...],
"names": [str, …],
}
де:
- documents_ids - список ID документів, яким буде присвоєно новостворені ярлики;
- names - список назв ярликів, які потрібно створити. Ярлик не повинен існувати у
системі;
Формат відповіді
Статус:
- 201 - всі ярлики було створено у системі і присвоєно наданим документам;
- 400 - неправильно сформований запит або ярлик вже існує в компанії;
- 403 - немає доступу до одного до одного або більше документів;
[
{
"id": str,
"name": str
},
….
]
Присвоєння існуючого ярлика документу
Формат запиту
POST /api/v2/tags/documents/connections
{
"documents_ids": [str, ...],
"tags_ids": [str, …],
}
де:
- documents_ids - список ID документів, яким буде присвоєно існуючі ярлики;
- tags_ids - список ID ярликів, які потрібно присвоїти документам;
Формат відповіді
Статус:
- 200 - ярлики були присвоєні документам;
- 400 - один або більше ярликів не існують в компанії;
- 403 - немає доступу до одного до одного або більше документів, немає доступу до
одного або більше ярликів;
Роз’єднання ярлика і документа
Формат запиту
DELETE /api/v2/tags/documents/connections
{
"documents_ids": [str, ...],
"tags_ids": [str, …],
}
де:
- documents_ids - список ID документів для роз’єднання;
- tags_ids - список ID ярликів для роз’єднання;
Формат відповіді
Статус:
- 200 - ярлики були від'єднані від документів;
- 400 - один або більше ярликів не існують в компанії;
- 403 - немає доступу до одного до одного або більше документів, немає доступу
до одного або більше ярликів;
Зверніть увагу: ярлик без документу або ролі не може існувати у системі Вчасно, тому
після видалення всіх документів з певним ярликом, цей ярлик автоматично
видаляється з системи.
Створення нового ярлика і присвоєння
співробітнику
Формат запиту
POST /api/v2/tags/roles
{
"roles_ids": [str, ...],
"names": [str, …],
}
де:
- roles_ids - список ID ролей співробітників, яким буде присвоєно ярлики;
- names - список назв ярликів, які потрібно створити. Ярлик не повинен існувати у
системі;
Формат відповіді
Статус:
- 201 - всі ярлики було створено у системі і поєднано з наданими співробітниками;
- 400 - неправильно сформований запит, ярлик вже існує в компанії, роль не існує в
системі або у запит містить ID неактивної ролі;
- 403 - один або декілька ролей не є співробітниками вашої компанії.
Зверніть увагу: оскільки за допомогою даної операції можна надавати право
переглядати документи з такими ж ярликами, то для виконання запиту потрібно мати
права адміністратора в компанії.
Присвоєння існуючого ярлика співробітнику
Формат запиту
POST /api/v2/tags/roles/connections
{
"roles_ids": [str, ...],
"tags_ids": [str, …],
}
де:
- roles_ids - список ID ролей співробітників, яким буде присвоєно ярлики;
- tags_ids - список ID ярликів, які будуть присвоєні співробітникам;
Формат відповіді
Статус:
- 200 - ярлики були присвоєні співробітникам;
- 400 - неправильно сформований запит, ярлик не знайдено у компанії, роль не існує в
системі або у запит містить ID неактивної ролі;
- 403 - один або декілька ролей не є співробітниками вашої компанії, немає доступу
до одного або більше ярликів;
Зверніть увагу: оскільки за допомогою даної операції можна надавати право
переглядати документи з такими ж ярликами, то для виконання запиту потрібно мати
права адміністратора в компанії.
Роз’єднання ярлика і ролі співробітника
Формат запиту
DELETE /api/v2/tags/roles/connections
{
"roles_ids": [str, ...],
"tags_ids": [str, …],
}
де:
- roles_ids - список ID ролей співробітників для роз’єднання;
- tags_ids - список ID ярликів для роз’єднання;
Формат відповіді
Статус:
- 200 - ярлики були від'єднані від співробітників;
- 400 - неправильно сформований запит, ярлик не знайдено у компанії, роль не
існує в системі або у запит містить ID неактивної ролі;
- 403 - один або декілька ролей не є співробітниками вашої компанії, немає
доступу до одного або більше ярликів;
Зверніть увагу: ярлик без документу або ролі не може існувати у системі Вчасно, тому
після видалення всіх документів з певним ярликом, цей ярлик автоматично
видаляється з системи.
Зверніть увагу: оскільки за допомогою даної операції можна позбавляти права
переглядати документи з такими ж ярликами, то для виконання запиту потрібно мати
права адміністратора в компанії.
Коментарі до документів
Отримання коментарів
Формат запиту
GET /api/v2/documents/comments
Підтримуються наступні параметри запиту:
- date_from (datetime) - повертаються коментарі із датою більшою або рівною за
вказану;
- date_to (datetime) - повертаються коментарі із датою меншою або рівною за
вказану;
- cursor - отримання наступної партії коментарів.
Формат відповіді
{
"comments": [
{
"id": str,
"text": str,
"document_id": str,
"date_created": datetime,
"email": str,
"edrpou": str,
"is_internal": bool
"type": "comment" | "rejection",
}
],
"next_cursor": str
}
де:
- id - id коментаря;
- text - коментар;
- document_id - id документу;
- date_created - дата створення;
- email - email співробітника;
- edrpou - ЄДРПОУ/ІПН компанії;
- is_internal - коментар співробітникам чи контрагентам;
- type - тип запису (comment - коментар до документа, rejection - причина відхилення
документа);
- next_cursor - значення для отримання наступної партії коментарів.
Отримання коментарів до документу
Формат запиту
GET /api/v2/documents/<document_id>/comments
Формат відповіді
"comments":
{
“id”: str,
"text": str,
"type": "comment" | "rejection",
"author":
{
"first_name": str,
"second_name": str,
"last_name": str,
"email": str,
"edrpou": str,
"is_legal": bool // true якщо юр. особа
},
"date_created": datetime
}
де:
- type:
- comment - коментар до документа;
- rejection - причина відхилення документа.
Додавання коментарів
Формат запиту
POST /api/v2/documents/<document_id>/comments
В залежності від хедеру Content-Type, тіло запиту може бути XML або JSON.
1) Для Content-Type: application/xml:
<comment>
<text>Тіло</text>
</comment>
2) Для Content-Type: application/json:
{
"text": "Тіло"
"is_internal": true/false (false по замовчуванню)
}
де:
- text - коментар;
- is_internal - коментар співробітникам чи контрагентам.
Внутрішнє погодження
Історія погодження
Формат запиту
GET /api/v2/documents/<document_id>/reviews
де:
document_id - id документу у Вчасно
Формат відповіді
[
{
"user_email": str,
"group_name": str,
"is_last": bool,
"action": str,
"date_created": str
}
]
де
user_email - email співробітника;
group_name - назва групи користувачів;
is_last - позначка останньої дії співробітника;
action - дія (approve - погоджено, reject - відхилено);
date_created - час виконання дії.
Запити на погодження
Формат запиту
GET /api/v2/documents/<document_id>/reviews/requests
де:
document_id - id документу у Вчасно
Формат відповіді
[
{
"user_from_email": str,
"user_to_email": str,
"group_to_name": str,
"status": str,
"date_created": str
}
]
де
user_from_email - email співробітника, що додав погоджувача;
user_to_email - email співробітника доданого до погодження;
group_to_name - назва групи, доданої до погодження;
status - статус запиту (active - співробітника додано до погодження, deleted співробітника видалено із погодження);
date_created - час виконання запиту.
Загальний статус погодження документу
Формат запиту
GET /api/v2/documents/<document_id>/reviews/status
де:
document_id - id документу у Вчасно
Формат відповіді
{
"status": str,
"is_required": bool,
"date_created": str,
"date_updated": str
}
де
status - статус погодження (pending - очікує погодження, approved - погоджено, rejected
- відхилено);
is_required - заборона підпису до погодження (true/false);
date_created - час початку процесу погодження;
date_updated - час останньої дії.
Додавання співробітника до погодження
Формат запиту
POST /api/v2/documents/<document_id>/reviews/requests
Формат запиту:
{
"user_to_email" | ”group_to_name”: str,
"is_parallel": bool
}
де:
document_id - id документу у Вчасно;
user_to_email - email співробітника;
group_to_name - назва групи, яка має погодити
is_parallel - паралельне чи послідовне погодження.
user_to_email, group_to_name - не можуть бути передані одночасно.
Формат відповіді
Статус:
- 201 - співробітника додано до погодження.
Видалення співробітника із погодження
Формат запиту
DELETE /api/v2/documents/<document_id>/reviews/requests
Формат запиту:
{
"user_to_email" | ”group_to_name”: str,
}
де:
document_id - id документу у Вчасно;
user_to_email - email співробітника.
group_to_name - назва групи
Формат відповіді
Статус:
- 204 - співробітника видалено із погодження.
Додаткові параметри
Створення додаткового параметру
Формат запиту
POST /api/v2/fields
{
"name": str,
"field_type": str,
"is_required": bool
}
де:
name - назва додаткового параметру;
field_type - тип параметру (text - текстовий, number - числовий, date - дата, enum один з переліку);
is_required - ознака обов'язковості (true/false).
Формат відповіді
Статус:
- 201 - створено додатковий параметр.
{
"id": str,
"order": str
"company_id": str,
"name": str,
"type": str,
"is_required": bool,
"created_by": str
}
де:
id - id додаткового параметру;
order - порядковий номер параметру;
company_id - id компанії, для якої створено параметр;
name - назва параметру;
type - тип параметру;
is_required - ознака обов'язковості;
created_by - id ролі користувача, що створив параметр.
Отримання списку додаткових параметрів
Формат запиту
GET /api/v2/fields
Формат відповіді
Статус:
- 200
[{
"id": str,
"name": str,
"type": str
}]
де:
id - id додаткового параметру;
name - назва параметру;
type - тип параметру (text - текстовий, number - числовий, date - дата, enum - один з
переліку).
Отримання додаткових параметрів документу
Формат запиту
GET /api/v2/documents/<document_id>/fields
Формат відповіді
Статус:
- 200
[{
"field_id": str,
"name": str,
"type": str,
"is_required": bool,
"value": str,
"date_updated": str,
"date_created": str
}]
де:
document_id - id документу у Вчасно;
field_id - id додаткового параметру;
name - назва параметру;
type - тип параметру (text - текстовий, number - числовий, date - дата, enum - один з
переліку);
is_required - ознака обов'язковості (true/false);
value - значення додаткового параметру;
date_updated - дата оновлення значення параметру;
date_created - дата створення параметру для документу.
Додавання додаткового параметру документу
Формат запиту
POST /api/v2/documents/<document_id>/fields
{
"field_id": str,
"value": str,
"is_required": bool
}
де,
document_id - id документу у Вчасно;
field_id - id додаткового параметру;
value - значення додаткового параметру;
is_required - ознака обов'язковості (true/false).
Формат відповіді
Статус:
- 201 - додано додатковий параметр.
Дочірні документи
Додавання дочірнього документа
Формат запиту
POST /api/v2/documents/<parent_document_id>/child/<child_document_id>
де:
parent_document_id - id головного документу, якому буде доданий дочірній;
child_document_id - id дочірнього документу.
Формат відповіді
Статус:
- 201 - додано дочірній документ;
- 200 - дочірній документ вже доданий.
Відкріплення дочірнього документа
Формат запиту
DELETE /api/v2/documents/<parent_document_id>/child/<child_document_id>
де:
parent_document_id - id головного документу, якому буде доданий дочірній;
child_document_id - id дочірнього документу.
Формат відповіді
Статус:
- 204 - дочірній документ відкріплено.
Підписи документів
Отримання списку підписів документа
Формат запиту
GET /api/v2/documents/<document_id>/signatures
де:
document_id - id документу у Вчасно
Формат відповіді
[{
“id": str,
"edrpou": str,
"company_name": str,
"is_internal": bool,
"role_id": str,
"signer_name": str,
"signer_position": str,
"serial_number": str,
"timestamp": datetime,
"has_stamp": bool,
"stamp": {
"acsk": str,
"company_name": str,
"edrpou": str,
"power_type": improved | qualified,
"serial_number": str,
"signer_name": str,
"signer_position": str | null,
"timestamp": datetime
}
}]
де:
id - id підпису;
edrpou - ЄДРПОУ компанії підписанта;
company_name - назва компанії;
is_internal - чи є внутрішнім підписом;
role_id - id ролі підписанта;
signer_name - ПІБ підписанта;
signer_position - посада;
serial_number - серійний номер сертифікату;
timestamp - мітка часу;
has_stamp - ознака печатки,
stamp - деталі печатки,
acsk - назва КНЕДП (АЦСК);
power_type - тип підпису (удосконалений, кваліфікований).
Отримання списку підписів багатостороннього
документа
Формат запиту
GET /api/v2/documents/<document_id>/flows
де:
document_id - id документу у Вчасно
Формат відповіді
[{
"edrpou": str,
"order": int | null,
"pending_signatures": int,
"emails": [str]
}]
де:
edrpou - ЄДРПОУ компанії підписанта
order - черга у разі почергового підписання (починаючи з 0)
pending_signatures - очікується підписів (0 - підписано)
emails - email підписанта
Відхилення документів
Формат запиту
POST /api/v2/documents/<document_id>/reject
{
"text": str
}
Content-Type: application/json
document_id - id документу у Вчасно
text - причина відхилення
Версії документів
Методи для роботи з версіями документів.
Інформацію про завантажені версії можна отримати за допомогою додаткового
параметру методів "Статуси вхідних\вихідних документів" (див. їх опис).
Завантажити оригінал версії можна параметром методу "Завантаження оригіналу
документа".
Завантажити версію до документу
Формат запиту
POST /api/v2/documents/<document_id>/version
Параметри форми тіла:
- file - документ до завантаження, підтримуються розширення .txt, doc, docx, xls, xlsx,
pdf.
Формат відповіді
Статус:
200 - версію завантажено.
Важливо:
Заголовок запиту повинен містити рядок Content-Type: multipart/form-data.
Видалити останню завантажену версію
Формат запиту
DELETE /api/v2/documents/<document_id>/version/<version_id>
Формат відповіді
Статус:
204 - версію видалено.
Додавання підпису до документу
1) Додавання підпису
Формат запиту
POST /api/v2/documents/<document_id>/signatures
{
"signature": <detached_signature_as_base64>,
"stamp": <detached_stamp_as_base64>
}
де:
document_id - документ до якого буде доданий підпис;
detached_signature_as_base64 - зовнішній підпис закодований в base64;
detached_stamp_as_base64 - зовнішня печатка закодована в base64 (не обов'язковий
параметр).
Увага! Методом надсилається саме готовий зовнішній (відкріплений) підпис чи печатка
(p7s), а не ключ підпису чи печатки (dat, zs2, sk, jks, pk8, pfx).
Підпис можливо додати до документу у статусі 7001, 7002 (вхідний), 7003, 7004
(вхідний), 7007 (вхідний), 7010.
2) Надсилання документу після додавання підпису
Формат запиту
POST /api/v2/documents/<document_id>/send
де:
document_id - документ до якого був доданий підпис;
УВАГА! Даним запитом також можливо надіслати документ на перший підпис
контрагенту, при статусі документа 7001.
Формат відповіді
Статус:
- 200 - документ надіслано контрагенту.
Групи користувачів
Методи для роботи з групами користувачів - створення, редагування, видалення груп
(CRUD)
Призначити групу у погоджувачі (прибрати з погоджувачів) можна за допомогою методів
"Додавання співробітника до погодження" та "Видалення співробітника із погодження"
Додавати групи до підписання можна за допомогою методу "Редагування підписантів
вхідного документа"
Отримати список груп компанії
Формат запиту
GET /api/v2/groups
Формат відповіді
[
{
"id": "99dac085-717b-46a6-a274-98c5ef233685",
"name": "АПІ Група тест",
"created_by": "e33027cf-3de0-4657-8a26-724f40bd2a41",
"date_created": "2023-12-13T19:05:14.874702+00:00",
"date_updated": "2023-12-13T19:05:14.874702+00:00",
},
…
]
Key
Type
Опис
id
uuid
ID групи
name
str
Назва групи
created_by
uuid
ID ролі, яка створила групу
date_created
datetime
Дата створення
date_updated
datetime
Дата оновлення
Отримати інформацію про групу
Формат запиту
GET /api/v2/groups/<group_id>
де <group_id> - ID групи, деталі якої потрібно отримати
Формат відповіді
{
"id": "99dac085-717b-46a6-a274-98c5ef233685",
"name": "АПІ Група тест",
"created_by": "e33027cf-3de0-4657-8a26-724f40bd2a41",
"date_created": "2023-12-13T19:05:14.874702+00:00",
"date_updated": "2023-12-13T19:05:14.874702+00:00",
}
Створити групу
Формат запиту
POST /api/v2/groups
{
"name": "АПІ Група тест"
}
Key
Type
Опис
name
str
Назва групи
Формат відповіді
{
"id": "99dac085-717b-46a6-a274-98c5ef233685",
"name": "АПІ Група тест",
"created_by": "e33027cf-3de0-4657-8a26-724f40bd2a41",
"date_created": "2023-12-13T19:05:14.874702+00:00",
"date_updated": "2023-12-13T19:05:14.874702+00:00",
}
Оновити назву групи
Формат запиту
PATCH /api/v2/groups/<group_id>
де <group_id> - ID групи, назву якої потрібно змінити
{
"name": "АПІ Група тест"
}
Формат відповіді
{
"id": "99dac085-717b-46a6-a274-98c5ef233685",
"name": "АПІ Група тест",
"created_by": "e33027cf-3de0-4657-8a26-724f40bd2a41",
"date_created": "2023-12-13T19:05:14.874702+00:00",
"date_updated": "2023-12-13T19:05:14.874702+00:00",
}
Видалити групу
Формат запиту
DELETE /api/v2/groups/<group_id>
де <group_id> - ID групи, яку потрібно видалити
Формат відповіді
Статус код відповіді - 204 No content
Отримати список учасників групи
Формат запиту
GET /api/v2/groups/<group_id>/members
де <group_id> - ID групи
Формат відповіді
[
{
"id": "dd89f8b8-dc38-47c7-ab68-8a0c0e019d8a",
"role_id": "7e0a5550-a46a-4482-9f87-d1ac71e37903",
"group_id": "99dac085-717b-46a6-a274-98c5ef233685",
"created_by": "e33027cf-3de0-4657-8a26-724f40bd2a41",
"date_created": "2023-12-13T19:05:25.841022+00:00"
},
…
]
Key
Type
Опис
id
uuid
ID учасника групи
role_id
uuid
ID ролі
group_id
uuid
ID групи
created_by
uuid
ID ролі, яка додала
учасника
date_created
datetime
Дата додавання учасника
до групи
Додати учасників до групи
Формат запиту
POST /api/v2/groups/<group_id>/members
{
"role_ids": [
"role_1_id",
…
"role_N_id"
]
}
де
●
●
<group_id> - ID групи, яку потрібно видалити
role_ids - Масив рядків типу "role_1_id", ..., "role_N_id" , де role_id - ID ролі, яку
потрібно додати до групи
Формат відповіді
[
{
"id": "dd89f8b8-dc38-47c7-ab68-8a0c0e019d8a",
"role_id": "7e0a5550-a46a-4482-9f87-d1ac71e37903",
"group_id": "99dac085-717b-46a6-a274-98c5ef233685",
"created_by": "e33027cf-3de0-4657-8a26-724f40bd2a41",
"date_created": "2023-12-13T19:05:25.841022+00:00"
},
…
]
Видалити учасників групи
Формат запиту
POST /api/v2/groups/<group_id>/members/remove
{
"group_members": [
"member_1_id",
…
"member_N_id"
]
}
де
●
●
<group_id> - ID групи, яку потрібно видалити
group_members - Масив рядків типу "member_1_id", ..., "member_N_id" , де
member_id - ID учасника групи, якого потрібно видалити
Формат відповіді
Статус відповіді - 204 No Content
Сценарії
Методи для роботи зі сценаріями компанії
Отримання списку сценаріїв компанії
Формат запиту
GET /api/v2/templates
Формат відповіді
Статус:
- 200
[
{
"id": "dfed9311-73ed-4b56-b06f-49822393240c",
"name": "Сценарій 1",
"review_settings": {
"is_required": false,
"reviewer_entities": [
{
"type": "role",
"id": "2293f182-e89d-4588-9713-6e6af63e1c94"
}
],
"is_ordered": false
},
"signers_settings": {
"is_ordered": false,
"signer_entities": [
{
"type": "role",
"id": "6e9e99f4-ccab-404b-8013-bc56cb97d352"
}
]
},
"viewers_settings": null,
"fields_settings": null,
"tags_settings": {
"tags": [
"сц1"
]
},
"created_by": "e33027cf-3de0-4657-8a26-724f40bd2a41",
"date_created": "2024-02-14T09:39:32.749529+00:00",
"date_updated": "2024-02-14T09:39:32.749529+00:00"
}
…
]
де:
●
●
id - id сценарію;
name - назва сценарію;
●
●
●
●
●
●
●
●
review_settings - налаштування погодження сценарію
signers_settings - налаштування підписання сценарію
viewers_settings - налаштування видачі доступів до документу співробітникам
сценарію
fields_settings - налаштування додаткових параметрів сценарію
tags_settings - налаштування ярликів сценарію
created_by - автор (власник) сценарію
date_created - дата створення сценарію
date_updated - дата оновлення сценарію.
Опис об’єкту review_settings
● is_required - чи є погодження обов’язковим (підписувати документ можна лише
після погодження)
● is_ordered - чи є погодження почерговим (якщо false, то погодження
паралельне)
● reviewer_entities - ролі та/або групи, які мають погодити документ. Об’єкт виду:
○ type - тип погоджувача, можливі варіанти role (роль користувача) та group
(група)
○ id - id ролі чи групи
● reviewers_ids (застарілий параметр, але поки підтримується) - масив з
переліком ID ролей, які мають погодити.
Опис об’єкту signers_settings
● is_ordered - чи є підписання почерговим (якщо false, то підписання паралельне)
● signer_entities - ролі та/або групи, які мають підписати документ. Об’єкт виду:
○ type - тип підписанта, можливі варіанти role (роль користувача) та group
(група)
○ id - id ролі чи групи
● signers_ids (застарілий параметр, але поки підтримується) - масив з
переліком ID ролей, які мають підписати.
Опис об’єкту viewers_settings
● viewers_ids - масив з переліком ID ролей, яким буде надано доступ до
документа.
Опис об’єкту fields_settings
● fields - масив об’єктів з описом додаткових параметрів, які будуть призначені на
документ. Складається з об’єктів виду:
○ field_id - ID додаткового параметра
○ value - його значення
○ is_required - чи є параметр обов’язковим до заповнення.
Опис об’єкту tags_settings
● tags - масив рядків з назвами ярликів, які будуть призначені сценарієм.
Отримання сценарію за його ID
Формат запиту
GET /api/v2/templates/<template_id>
де <template_id> - ID cценарію.
Структура відповіді аналогічна запиту “Отримання списку сценаріїв компанії”
Підписання хмарним ключем Вчасно.КЕП
Створення сесії підписання хмарним ключем
Формат запиту
POST /api/v2/cloud-signer/sessions/create
{
"duration": int,
"client_id": str
"use_refresh_token": bool
}
де:
duration - тривалість сесії в секундах. min = 60, max = 2592000 (30 днів)
client_id - ID хмарного ключа/печатки Вчасно.КЕП.
use_refresh_token - створення сесії з токеном оновлення. Опціональне поле, за
замовчуванням false. Якщо передано use_refresh_token: true то параметр duration буде
ігноруватись.
Формат відповіді
{
"authSessionId": str,
"isMobileLogged": bool,
"notUseSmartphone": bool
}
де:
authSessionId - ID сесії, необхідний для перевірки статусу
isMobileLogged - чи виконаний вхід власником ключа в додатку Вчасно.КЕП
notUseSmartphone - чи встановлений у власника ключа чекбокс “Не використовую
смартфон” в кабінеті Вчасно.КЕП.
Для створення сесії, IP адреса, з якої надсилається запит, має бути додана
співробітнику на якого сформовано токен Вчасно в список IP адрес з доступом до
підписання Вчасно.КЕП. Як додати?
При створенні сесії власник ключа отримає на телефон посилання, по якому треба
перейти та ввести пароль від ключа, або використати додаток.
При встановленому у власника ключа чекбоксі “Не використовую смартфон” в кабінеті
Вчасно.КЕП, потрібно ввести код із SMS на сторінці https://cs.vchasno.ua/sign.
Перевірка статусу сесії підписання хмарним ключем
Формат запиту
POST /api/v2/cloud-signer/sessions/check
{
"auth_session_id": str
}
де:
auth_session_id - ID сесії
Формат відповіді
{
"status": str
}
Коли користувач введе вірний пароль від ключа, або використає додаток, наступний
запит на перевірку статусу сесії поверне токен авторизації. Токен повертається лише
один раз.
{
"status": str,
"token": str
}
де:
status - статус сесії:
init - ініційовано запит на відкриття сесії, очікується підтвердження від
користувача;
ready - сесія відкрита, запит підтверджено користувачем. У відповіді токен;
provided - сесія відкрита, токен був повернутий в минулому запиті;
canceled - сесія закрита примусово (наразі не використовується);
expired - сесія завершена по строку дії.
token - токен сесії, необхідний для авторизації запитів на підписання.
Перевірка статусу сесії підписання хмарним ключем,
створеної з use_refresh_token: true
Формат запиту
POST /api/v2/cloud-signer/sessions/refresh/check
{
"auth_session_id": str
}
де:
auth_session_id - ID сесії
Формат відповіді
{
"status": str
}
Коли користувач введе вірний пароль від ключа, або використає додаток, наступний
запит на перевірку статусу сесії поверне токени авторизації та оновлення. Токени
повертаються лише один раз.
{
"status": str,
"accessToken": str
"refreshToken": str
"expiresIn": int
}
де:
status - статус сесії:
init - ініційовано запит на відкриття сесії, очікується підтвердження від
користувача;
ready - сесія відкрита, запит підтверджено користувачем. У відповіді токен;
provided - сесія відкрита, токен був повернутий в минулому запиті;
canceled - сесія закрита примусово (наразі не використовується);
expired - сесія завершена по строку дії.
accessToken - токен сесії, необхідний для авторизації запитів на підписання.
refreshToken - токен для оновлення токена доступу.
expiresIn - на скільки секунд виданий токен доступу.
Оновлення токену доступу за допомогою токена оновлення
Формат запиту
POST /api/v2/cloud-signer/sessions/refresh
{
"auth_session_id": str
"refresh_token": str
}
де:
auth_session_id - ID сесії
refresh_token - токен для оновлення токена доступу
Формат відповіді
{
"status": str
"accessToken": str
"refreshToken": str
"expiresIn": int
}
де:
status - статус сесії:
init - ініційовано запит на відкриття сесії, очікується підтвердження від
користувача;
ready - сесія відкрита, запит підтверджено користувачем. У відповіді токен;
provided - сесія відкрита, токен був повернутий в минулому запиті;
canceled - сесія закрита примусово (наразі не використовується);
expired - сесія завершена по строку дії.
accessToken - токен сесії, необхідний для авторизації запитів на підписання.
refreshToken - токен для оновлення токена доступу.
expiresIn - на скільки секунд виданий токен доступу.
Після вдалого запиту на оновлення токена доступа, оновлюється також токен для
оновлення токена доступу (refreshToken).
Токени повертаються лише один раз.
Підпис документу з використанням хмарного ключа
Формат запиту
POST /api/v2/cloud-signer/sessions/sign-document
{
"auth_session_token": str,
"client_id": str,
"password": str,
"document_id": str
}
або
{
"access_token": str,
"client_id": str,
"password": str,
"document_id": str
}
●
●
●
●
В залежності від того, чи було передано при створенні сесії підписання
use_refresh_token=true, потрібно передавати токен сесії у відповідне поле:
○ auth_session_token - для сесії без use_refresh_token параметра, або з
use_refresh_token=false
○ access_token - для сесії з use_refresh_token=true
client_id - ID хмарного ключа/печатки Вчасно.КЕП
password - Пароль від ключа
document_id - ID документу на Вчасно
Формат відповіді
Статус:
- 201 Created
Для зміни статусу підписаного документу, необхідно виконати дію по надсиланню
документу.
Інтеграція з особистим кабінетом
Створення сесії перегляду або підписання
документу
Формат запиту
POST /api/v2/sign-sessions
{
"document_id": str,
"edrpou": str,
"email": str,
"type": str,
"on_cancel_url": str,
"on_finish_url": str
}
де:
- document_id - ID документа, для якого буде створена сесія перегляду;
- email - пошта користувача, для якого буде створена сесія перегляду;
- edrpou - ЄДРПОУ користувача, для якого буде створена сесія перегляду;
- type - тип створеної сесії:
Для сесії перегляду документу - "view_session".
Для сесії підписання документу - “sign_session”
- on_cancel_url - адреса, куди буде направлено користувача у випадку відхилення
документу;
- on_finish_url - адреса, куди буде направлено користувача при успішному підписанні
документу.
Важливо
При створенні сесії для контрагента:
- документ з першим підписом від власника (first_sign_by = "owner") має бути
підписаним та відправленим (статус 7004);
- документ з першим підписом від контрагента (first_sign_by = "recipient"), який
знаходиться в статусі 7000 або 7001, буде автоматично відправленим
Формат відповіді
Статус:
- 201 - нова сесія перегляду створена для вказаного користувача;
- 200 - нова сесія перегляду не створена, відображені дані сесії, створеної раніше;
- 400 - вказаний користувач не має права на перегляд вказаного документу;
- 403 - користувач має недостатньо прав на створення сесії перегляду документу;
{
"created_by": str,
"document_id": st,
"document_status": Optional[str],
"edrpou": str,
"email": str,
"id": str,
"is_legal": bool,
"on_cancel_url": str,
"on_finish_url": str,
"on_document_comment_hook": Optional[str],
"on_document_reject_hook": Optional[str],
"on_document_sign_hook": Optional[str],
"on_document_view_hook": Optional[str],
"role_id": str,
"status": str,
"type": str,
"url": str, # Необхідний URL сесії перегляду документу
"vendor": str
}
*Під час сесії перегляду документу, користувачу доступна функція перегляду
коментарів.
Керування обліковими записами співробітників
компанії
Запрошення 1+ нових співробітників за допомогою Email
Формат запиту
POST /api/v2/invite/coworkers
{
“emails”: [str, ...]
}
Де,
email - email користувача, що має бути запрошеним до поточної компанії
УВАГА! Запрошувати співробітників до поточної компанії має можливість тільки роль
(ролі) з відповідними правами
Налаштування прав доступу та нотифікації
Формат запиту
'PATCH' /api/v2/roles/{role_id}
{
"user_role": int,
"position": str,
"allowed_ips": [str, ...],
"allowed_api_ips": [str, ...],
"can_view_document": bool,
"can_comment_document": bool,
"can_upload_document": bool,
"can_download_document": bool,
"can_print_document": bool,
"can_delete_document": bool,
"can_sign_and_reject_document": bool,
"can_invite_coworkers": bool,
"can_edit_company": bool,
"can_edit_roles": bool,
"can_create_tags": bool,
"can_edit_document_templates": bool,
"can_edit_document_fields": bool,
"show_child_documents": bool
"can_receive_notifications": bool,
"can_receive_inbox": bool,
"can_receive_comments": bool,
"can_receive_rejects": bool,
"can_receive_reminders": bool,
"can_receive_access_to_doc": bool,
"can_receive_delete_requests": bool,
"can_receive_reviews": bool
}
Де,
Налаштування прав доступу:
user_role - Адміністратор компанії (8001 - адмін; 8000 - не адмін)
position - Посада
allowed_ips - Доступ тільки з певних IP адрес. IP адреса може бути постійною або
змінною. Якщо IP адреса змінна – вкажіть ту частину адреси, що буде повторюватись у
форматі XXX*
allowed_api_ips - IP адреси, з котрих можна направляти запити на авторизацію та
підписання документів хмарним підписом "Вчасно.КЕП". Якщо IP адреса змінна –
вкажіть ту частину адреси, що буде повторюватись у форматі XXX*
can_view_document - Перегляд всіх документів компанії
can_comment_document - Коментування документів
can_upload_document - Завантаження документів у сервіс
can_download_document - Вивантаження документів на локальний комп’ютер
can_print_document - Друк документів
can_delete_document - Видалення документів
can_sign_and_reject_document - Підписання та відхилення документів
can_invite_coworkers - Запрошення співробітників
can_edit_company - Редагування інформації про компанію
can_edit_roles - Редагування та видалення співробітників
can_create_tags - Створення нових ярликів
can_edit_document_templates - Налаштування сценаріїв документів
can_edit_document_fields - Налаштування параметрів документів
show_child_documents - Відображати дочірні документи у списку документів
Налаштування нотифікації:
can_receive_notifications - Отримувати всі сповіщення про події в цій компанії
can_receive_inbox - Email про отримання документів
can_receive_comments - Email про отримання коментарів
can_receive_rejects - Email про відхилення документів
can_receive_reminders - Email про нагадування про неопрацьовані запити у сервісі
can_receive_access_to_doc - Email про отримання доступу до документа
can_receive_delete_requests - Email із запитом на видалення документів
can_receive_reviews - Email про погодження документів
УВАГА!
1) Надання ролі статуса адміністратора компанії, автоматично вмикає всі права для цієї
ролі;
2) Налаштування нотифікації відбувається відповідно до налаштувань у
веб-інтерфейсі, а саме:
- Пункт “Отримувати всі сповіщення про подіїї в ції компаніі”, автоматично відповідно
вмикає або вимикає інші пункти налаштувань нотифікації
- Інші пункти нотифікації, можливо увімкнути або вимкнути незалежно від пункту
“Отримувати всі сповіщення про події в цій компанії”;
Тобто, якщо потрібно вимкнути всі сповіщення, але залишити сповіщення про
відхилення документів - потрібно зробити два запити:
У першому - can_receive_notifications : false
У другому - can_recieve_rejects : true
3) Змінювати налаштувань прав доступу своїх та інших співробітників, має можливість
роль за відповідними правами
Видалення облікового запису співробітника
Формат запиту
DELETE /api/v2/roles/{role_id}
УВАГА!
Видаляти облікові записи співробітників компанії має можливість роль з відповідними
правами.
Створення облікового запису співробітника
На відміну від запрошення співробітника при якому на вказаний email надходить лист із
запрошенням зареєструвати користувача/приєднатись до компанії власноруч, дана дія
призводить до завершенного створення співробітника в компанії, а на вказаний email
надходить лист з логіном та паролем, для авторизації.
Формат запиту
POST /api/v2/coworker
{
“email“: [str]
“first_name“: [str]
“second_name“: [str]
“last_name“: [str]
“phone“: [str]
}
Де,
email - електронна адреса користувача
Електронна адреса повинна співпадати з доменним ім'ям компанії і не бути
зареєстрованою у сервісі Вчасно. Для питань з приводу доменного ім'я компанії
зверніться до служби підтримки.
first_name - ім'я користувача (не обов'язково)
second_name - по батькові (не обов'язково)
last_name - призвище (не обов'язково)
phone - номер телефону (не обов'язково)
(У форматі +380ХХХХХХХХХ. Користувачеві власноруч потрібно буде
підтвердити номер телефону у налаштуваннях користувача в особистому кабінеті)
Увага! Для роботи з методом необхідно прикріплення корпоративного домену компанії
до облікового запису.
Для прикріплення домену зверніться на службу підтримки.
Отримання списку активних співробітників та їх ID ролей
Формат запиту
GET /api/v2/roles
Формат відповіді
Статус:
- 200
{
"roles": [
{
"id": str,
"status": "active",
"date_created": str,
"email": str,
"position": str
}
]
}
де,
id - id ролі співробітника;
status - статус ролі (active);
date_created - дата запрошення співробітника в компанію;
email - email співробітника;
position - посада.
Формування токена користувача
Формат запиту
POST /api/v2/tokens
{
"emails": [str],
"expire_days": str
}
де:
emails - email співробітника(ів), котрим необхідно сформувати токен;
expire_days - тривалість життя токену у днях (необов'язковий параметр)
Скидання токена користувача
Формат запиту
DELETE /api/v2/tokens
{
"emails": [str]
}
де:
emails - email співробітника(ів), котрим необхідно скинути токен;
Увага! Сформувати та скинути токен може тільки роль із правами адміністратора.
Відновлення користувача
Формат запиту
'PATCH' /api/v2/roles/{role_id}
{
"status": "active"
}
Завантаження списку дій співробітників з
документами за останні 30 днів
Формат запиту
GET /api/v2/actions/documents.csv
УВАГА! Доступ до методу має тільки роль (ролі) із правами адміністратора.
Отримання списку дій співробітників
Формат запиту
GET /api/v2/events
Підтримуються наступні параметри запиту:
- date_created_from (datetime) - повертаються записи про дії співробітників із
датою більшою або рівною за вказану;
- date_created_to (datetime) - повертаються записи про дії співробітників із датою
меншою або рівною за вказану;
- cursor - отримання наступної партії записів дій (100 шт).
Формат відповіді
Статус:
- 200
{
"results": [
{
"event_time": str,
"email": str,
"feature": str,
"event": str,
"status": str,
"subject_email": str,
"details": str
}
],
"next_cursor": str | null
}
де:
event_time - дата та час дії;
email - email співробітника, який виконував дію;
feature - тип дії;
event - дія;
status - статус виконання дії;
subject_email - email співробітника, з яким проводилась дія;
details - деталі по дії;
next_cursor - токен пагінації, використовується для отримання наступної партії записів
дій.
УВАГА! Доступ до методу має тільки роль (ролі) із правами адміністратора.
Перевірка реєстрації контрагента
Формат запиту
POST /api/v2/check/company
{
"edrpou": str
}
де,
edrpou - код ЄДРПОУ/ІПН контрагента
Формат відповіді
Статус: 200
{
"edrpou": str,
"name": str,
"is_registered": bool
}
де,
edrpou - код ЄДРПОУ/ІПН контрагента,
name - назва компанії/ФОП,
is_registered - реєстрація (true - зареєстровано/false - не зареєстровано)
Перевірка реєстрації списку контрагентів з
файлу
Запит для перевірки реєстрації списку контрагентів. На вхід приймає .xslx або .csv
файл наступного виду:
ЄДРПОУ/ІПН
ЄДРПОУ1
ЄДРПОУ2
…
Формат запиту
POST /api/v2/check/company/upload
Параметри форми тіла:
- file - файл до завантаження, підтримуються розширення .xslx або .csv.
Важливо:
Заголовок запиту повинен містити рядок Content-Type: multipart/form-data.
Формат відповіді
Статус: 200
{
"companies": [
{
"edrpou": str,
"name": str,
"is_registered": bool
}
],
"percentage": str,
"invalid_row_numbers": [str],
"rows_invalid": str,
"rows_total": str
}
де,
edrpou - код ЄДРПОУ/ІПН контрагента,
name - назва компанії/ФОП,
is_registered - реєстрація (true - зареєстровано/false - не зареєстровано)
percentage - відсоток зареєстрованих компаній;
invalid_row_numbers - номери некоректних строк у файлі;
rows_invalid - кількість некоректних строк у файлі;
rows_total - загальна кількість строк.
Приклад роботи
#!/bin/bash
set -e
API_HOST=${API_HOST:-https://vchasno.ua}
API_TOKEN=${API_TOKEN:-1a1B1c1}
# Завантаження PDF файла
curl -X POST \
-F 'file=@file.pdf' \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/documents?first_sign_by=owner&expected_owner_signatures=2&expect
ed_recipient_signatures=1
echo
echo "1 файл завантажено у сервіс Вчасно"
echo
# Завантаження архіва з PDF файлами
curl -X POST \
-F 'file=@archive.zip' \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/documents
echo
echo "Х файлів завантажено у сервіс Вчасно"
echo
# Завантаження файла з вказанням кількості та осіб підписантів
POST
/api/v2/documents?expected_owner_signatures=2&expected_recipient_signatures=3&signe
r_roles=1111111111111111111111111&signer_roles=22222222222222222222222222&parallel
_signing=false
expected_owner_signatures - кількість підписів компанії-відправника
expected_recipient_signatures - кількість підписів компанії-отримувача
signers - ID ролі користувача (id користувача в певній компанії)
parallel_signing - паралельне чи почергове підписання користувачами.
# Отримання статусів завантажених документів
curl -X GET \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/documents
echo
echo "Всі файли користувача, котрі завантажені у сервіс Вчасно"
# Отримання статусів документів, які були завантажені у липні
curl -X GET \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/documents?date_from=2019-07-01&date_to=2019-07-31
echo
echo "Всі файли користувача, котрі завантажені у сервіс Вчасно у липні"
# Отримання статусів документів за переліком ID
curl -X GET \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/documents?ids=id1&ids=id2
# Отримання документів, підписаних усіма
curl -X GET \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/documents?status=7008
echo
echo "Підписані документи"
# Отримання документів за vendor_id
curl -X GET \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/documents?vendor_id=<vendor_id>
echo
echo "Документи із заданим vendor_id"
# Отримання документів, завантажених за допомогою API
curl -X GET \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/documents?vendor=API
echo
echo "Документи із vendor=API"
# Отримання документів із датами документу за заданий період
curl -X GET \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/documents?date_document_from=2019-01-01&date_document_to=201
9-01-31
echo
echo "Документи, створені у січні 2019"
# Отримання документів, що були відхилені та залишилися відхиленими у
заданий період
curl -X GET \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/documents?date_rejected_from=2019-01-01&date_rejected_to=2019-01
-31
echo
echo "Документи, відхилені у січні 2019 і залишилися відхиленими у січні 2019"
# Отримання статусу 1 завантаженого документа
# <document_id> можна отримати з попереднього запиту або з відповіді на
завантаження документів
curl -X GET \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/documents/<document_id>
echo
echo "Файл користувача, який завантажений в сервіс Вчасно"
# Отримання вхідних документів, які були створені у січні 2017
curl -X GET \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/incoming-documents?date_created_from=2017-01-01&date_created_to
=2017-01-31
# Отримання документів для завантаження за переліком ID
curl -X GET \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/download-documents?ids=id1&ids=id2
# Завантаження оригіналу документа
curl -X GET \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/documents/<document_id>/original
# Додавання коментаря
curl -X POST \
-H "Authorization: ${API_TOKEN}" \
-d '{"text": "Text"}'
$API_HOST/api/v2/documents/<id>/comments
# Видалення документа
curl -X DELETE \
-H "Authorization: ${API_TOKEN}" \
$API_HOST/api/v2/documents/<document_id>
# Отримання тегів документу
curl -X GET \
-H "Authorization: ${API_TOKEN}" \
"$API_HOST/api/v2/documents/<id>?with_tags=1"
# Створення ярликів для документу.
curl -X POST \
-H "Authorization: ${API_TOKEN}" \
-d '{"documents_ids": ["DOC_ID"], "names": ["TEST 1", "TEST 2"]}'
$API_HOST/api/v2/tags/documents
# Присвоєння існуючих ярликів документу.
curl -X POST \
-H "Authorization: ${API_TOKEN}" \
-d '{"documents_ids": ["DOC_ID"], "tags_ids": ["TAG_ID"]}'
$API_HOST/api/v2/tags/documents/connections
# Роз’єднання існуючих ярликів і документів.
curl -X DELETE \
-H "Authorization: ${API_TOKEN}" \
-d '{"documents_ids": ["DOC_ID"], "tags_ids": ["TAG_ID"]}'
$API_HOST/api/v2/tags/documents/connections
# Створення ярликів для співробітника.
curl -X POST \
-H "Authorization: ${API_TOKEN}" \
-d '{"roles_ids": ["ROLE_ID"], "names": ["TEST 1", "TEST 2"]}'
$API_HOST/api/v2/tags/roles
# Присвоєння існуючих ярликів співробітнику.
curl -X POST \
-H "Authorization: ${API_TOKEN}" \
-d '{"roles_ids": ["ROLE_ID"], "tags_ids": ["TAG_ID"]}'
$API_HOST/api/v2/tags/roles/connections
# Роз’єднання існуючих ярликів і співробітників.
curl -X DELETE \
-H "Authorization: ${API_TOKEN}" \
-d '{"roles_ids": ["ROLE_ID"], "tags_ids": ["TAG_ID"]}'
$API_HOST/api/v2/tags/roles/connections
Можливі помилки
400_rate_upload_overlimit - перевищено дозволений обсяг документів для
завантаження. Перевірте тариф в кабінеті;
403_access_denied - для доступу до API потрібно оплатити тариф 'Інтеграція';
403_login_required - необхідно оновити токен у налаштуваннях, або токен не був
переданий у запиті;
429_too_many_requests - перевищено ліміт запитів, необхідно повторити запит через
деякий час.