API v2

Алгоритми обміну документами (API)

Підказка

Всі запити нижче перерахованих API методів платформи EDIN 2.0 направляються на адресу: https://edo-v2.edin.ua

Авторизація

Метод	URL запиту	Опис
POST	`/api/authorization/hash`	Авторизація

Робота з довідниками

Метод	URL запиту	Опис
GET	`/api/oas/user`	Отримання інформації по авторизованому користувачу
GET	`/api/oas/account/users`	Отримання інформації про всіх користувачів компанії (на рівні акаунта)
GET	`/api/oas/account/identifiers`	Отримання інформації по GLN номерами, пов’язаним з авторизованим користувачем (на рівні акаунта)
GET	`/api/oas/retailers`	Отримання переліку роздрібних мереж, які пов’язані із заданим GLN
GET	`/api/oas/retailer/identificators`	Отримання переліку GLN номерів, які пов’язані із заданою роздрібною мережею
GET	`/api/oas/allretailers`	Отримання переліку всіх мереж
GET	`/api/oas/units`	Отримання переліку доступних одиниць виміру
GET	`/api/oas/identifiers`	Отримання інформації про організацію по Назві/ІПН/КПП/GLN

Робота з об’єднаним віртуальним довідником (всі сервіси в рамках акаунта/користувача)

Метод	URL запиту	Опис
GET	`/api/uds/dictionary`	Отримати значення з віртуального довідника
POST	`/api/uds/dictionary`	Створити новий довідник
PUT	`/api/uds/dictionary`	Оновити довідник
DELETE	`/api/uds/dictionary`	Видалити довідник
POST	`/api/uds/dictionary/values`	Додати значення в довідник
DELETE	`/api/uds/dictionary/values`	Видалити значення з довідника

Робота з документами

Метод	URL запиту	Опис
POST	`/api/v2/eds/doc`	Створення чернетки документа
PATCH	`/api/eds/doc/send`	Відправка чернетки
POST	`/api/eds/doc/create_and_send`	Відправка документа (без створення чернетки)
POST	`/api/eds/docs/search`	Пошук документів (з фільтрацією), вибір списку документів
GET	`/api/eds/doc`	Отримання інформації (мета-даних) про документ
GET	`/api/eds/chain`	Отримання конкретного ланцюжка документів
GET	`/api/eds/doc/body`	Отримання контента документа
GET	`/api/eds/doc/xml`	Отримання XML контента документа
GET	`/api/eds/doc/download`	Завантажити тіло документа/підпису
GET	`/api/eds/doc/condra/body`	Завантажити «Неструктурований (універсальний) документ» (CONDRA) в вигляді архіву
PATCH	`/api/eds/doc/condra/send`	Відправка «Неструктурованого (універсального) документа» (CONDRA)
POST	`/api/v2/eds/doc/condra/create`	Створення чернетки «Універсального/неструктурованого документа» (CONDRA)
POST	`/api/v2/eds/doc/condra/create_and_send`	Створення й відправка «Універсального/неструктурованого документа» (CONDRA) без створення чернетки
POST	`/api/eds/doc/statuses`	Відправка статусу документа
GET	`/api/eds/doc/statuses`	Отримання статусу документа
POST	`/api/eds/doc/body`	Додавання файла-вкладення (для CONDRA)
POST	`/api/eds/doc`	Створення чернетки документа (для CONDRA та TRANSPORTATIONORDER)
PUT	`/api/eds/doc`	Редагування чернетки документа
GET	`/api/office/uuid`	Отримання UUID (для CONDRA)
POST	`/api/eds/doc/body`	Підписання файла (для CONDRA)
PUT	`/api/eds/doc/extra_fields`	Заповнення індексів (додавання / оновлення полей екстрапараметрів)
PATCH	`/api/eds/chain/archive`	Архівування / Розархівування ланцюжка документів
GET	`/api/eds/doc/reports/doctype`	Отримати реєстр документів в xls форматі
GET	`/api/eds/doc/print`	Роздрукувати вкладення документа
POST	`/api/eds/doc/attachment/sign`	Додавання підпису до вкладень документа-чернетки
GET	`/api/eds/doc/attachment/sign/hash`	Отримати хеш вкладення (контейнера) документа для підписання
GET	`/api/eds/doc/attachment/sign/info`	Отримання інформації про підпис/підписантів
PATCH	`/api/v2/eds/condra/reject`	Відхилити «Універсальний/неструктурований документ» (CONDRA). Створення квитанції №13
PATCH	`/api/v2/eds/condra/withdraw`	Відкликати «Універсальний/неструктурований документ» (CONDRA). Створення квитанції №14
PATCH	`/api/v2/eds/condra/confirm/send`	Прийняти «Універсальний/неструктурований документ» (CONDRA)
DELETE	`/api/eds/doc/attachment`	Видалити файл-вкладення (чернетка)
GET	`/api/eds/doc/attachment`	Отримати файл-вкладення
POST	`/api/eds/doc/attachment`	Додати файл до документа-чернетки
PATCH	`/api/eds/docs`	Видалити документи-чернетки
POST	`/api/v2/eds/doc/content`	Отримати тіла документів (json) за вказаними UUID

Робота з квитанціями

Метод	URL запиту	Опис
GET	`/api/eds/doc/tickets`	Отримання всіх квитанцій вказаного документа
GET	`/api/eds/doc/signers`	Отримання інформації про підписантів
GET	`/api/v2/eds/doc/signers`	Отримати інформацію про підписантів за всіма вказаними транзакціями документа
GET	`/api/eds/doc/ticket/body`	Отримання даних/контенту квитанції
GET	`/api/v2/eds/comdoc/repeal`	Створення на сервері квитанції «Анулювання» (COMDOC_019)
GET	`/api/v2/eds/comdoc/reject`	Створення на сервері квитанції «Повідомлення про відмову від підписання документу» (COMDOC_021) для COMDOC/TRANSPORTATIONORDER документів
GET	`/api/v2/eds/doc/reject`	Створення на сервері квитанції «Повідомлення про відмову від підписання документу» (COMDOC_021)
POST	`/api/v2/eds/doc/ticket`	Створення квитанції №1 (підпис чернетки)
POST	`/api/v2/eds/comdoc/accept`	Створення квитанції №2 (прийняття документа COMDOC)
POST	`/api/v2/eds/comdoc/repeal`	Створення квитанції №11 (запит на анулювання COMDOC/TRANSPORTATIONORDER)
POST	`/api/v2/eds/comdoc/repeal/accept`	Створення квитанції №12 (прийняття запиту на анулювання COMDOC/TRANSPORTATIONORDER)
POST	`/api/v2/eds/comdoc/reject`	Створення квитанції №13 (відхилення документа COMDOC/TRANSPORTATIONORDER)
POST	`/api/v2/eds/comdoc/revoke`	Створення квитанції №14 (відкликати підписання документа COMDOC/TRANSPORTATIONORDER)
POST	`/api/v2/eds/comdoc/repeal/reject`	Створення квитанції №15 (відмова від анулювання COMDOC)
POST	`/api/v2/eds/doc/reject`	Відправка відмови від підписання (створення квитанції №13)

Робота з тегами

Метод	URL запиту	Опис
POST	`/api/eds/tags`	Створити новий тег
GET	`/api/eds/tags`	Отримати теги
PUT	`/api/eds/tags`	Редагувати тег
DELETE	`/api/eds/tags`	Видалити теги
POST	`/api/eds/doc/tags`	Додати теги до документа
DELETE	`/api/eds/doc/tags`	Вилучити теги з документа

Робота з подіями (в тестуванні)

Примітка

Обираєте ідентифікатор документу, з якого Ви плануєте розпочати отримувати всі наступні події.
Надсилаєте запит на отримання останнього ідентифікатора події за документом.
В отриманному у відповідь об’єкті XEvent зберігаєте значення параметра id.
Надсилаєте запит для пошуку подій. В об’єкті запиту EventsStorageQuery, в параметрі fromId вказуєте ідентифікатор події який Ви отримали в пункті 3.
З отриманного у відповідь об’єкта EventsStorageQueryResult зберігаєте значення параметра lastEventId замість того, що зберегли в пункті 3.
Опрацьовуєте документи в EventsStorageQueryResult.
Якщо кількість значень в параметрі items об’єкта EventsStorageQueryResult:
- дорівнює вказаному ліміту (limit) або рівне 100, то повторюйте операції з 4 по 7.
- меньше вказаного ліміту (limit) або менше 100, то необхідно зробити паузу (1 хвилина) для подальшого виконання операцій з 4 по 7.

Метод	URL запиту	Опис
GET	`/api/eds/docs/event/last`	Отримати останню подію за документом
GET	`/api/eds/docs/events`	Отримати список подій
POST	`/api/eds/docs/events`	Пошук подій

Робота з файлами (вкладення до документа)

Метод	URL запиту	Опис
POST	`/api/eds/doc/attachment`	Додати файл до документа-чернетки
GET	`/api/eds/doc/attachment`	Отримати файл-вкладення
DELETE	`/api/eds/doc/attachment`	Видалити файл-вкладення (чернетка)

Погодження

Метод	URL запиту	Опис
POST	`/api/eds/doc/approval/scenario`	Створити сценарій погодження документів
GET	`/api/eds/doc/approval/scenario`	Отримати сценарій/-ії (на рівні GLN)
PUT	`/api/eds/doc/approval/scenario`	Редагувати / видалити сценарій погодження документів
POST	`/api/eds/doc/approval/step`	Запуск документа на погодження / Зміна статуса кроку погодження
GET	`/api/eds/doc/approval/step`	Отримання кроків погодження за документом

Підключення до мережі

Метод	URL запиту	Опис
GET	`/api/oas/retailers/requests`	Пошук заявки в «Підключення до мережі»

Опис помилок сервісу «EDI Network»

Код відповіді	Індекс помилки	Текст помилки	Опис
400	ERR_EDI-1	Validation document errors: [%s] Документ містить помилки: [%s]	Помилка при перевірці обовязкових тегів в xml - в дужках перелік незаповнених/некоректно заповнених полів
400	ERR_EDI-2	XSD Validation document error: [%s] Помилка валідації документа за XSD: [%s]	Помилка при валідації по xsd - в дужках вказується конктретна причина помилки
400	ERR_EDI-3	Business logic validation document errors: [%s] Документ містить помилки згідно бізнес-логіки: [%s]	Помилка при перевірці обовязкових тегів в xml згідно бізнес-логіки - в дужках перелік незаповнених/ некоректно заповнених полів
400	ERR_EDI-4	Unknown or unsupported document type: [%s] Невідомий або непідтримуваний тип документа: [%s]	Помилка виникає тільки в 1му випадку: при спробі відправити документ CONDRA методом create_and_send
400	ERR_EDI-5		Помилка виникає при перевірці підпису, якщо позначка часу створена офлайн
400	ERR_EDI-6	Data should contain [%s] marker Данні мають містити [%s] маркер	Помилка виникає при спробі дешифрування даних, якщо дані не містять крипто-заголовки (CERTCRYPT або UA1_CRYPT)
400	ERR_EDI-7	Data should be enveloped (crypted) Дані повинні бути захищені (зашифровані)	Помилка виникає при спробі дешифрування даних, якщо дані не зашифровані
400	ERR_EDI-8	Decription failed - [%s] Не вдалося розшифрувати - [%s]	Помилка виникає при спробі дешифрування даних, якщо при дешифруванні виникає помилка - в дужках причина
400	ERR_EDI-9	The data is not signed or contains an incorrect signature Дані не підписані або містять некоректний підпис	Помилка виникає коли клієнт передав не підписані або не коректно підписані дані, коли вони мають бути підписані (наприклад, роут create_and_send при відправці p7s-ки, вказуючи content-type = application/pkcs7-signature)
400	ERR_EDI-10	You cannot send a document signed only with a seal Ви не можете надіслати документ, підписаний тільки печаткою
400	ERR_EDI-11	GLN from request [%s] should match sender’s GLN from body [%s] GLN із запиту [%s] має збігатися з GLN відправника з тіла [%s]	Помилка виникає в create_and_send або роуті створення документа через API, коли є невідповідність GLN-ів, який був переданий в url-параметрі і GLN відправника в тілі документа
400	ERR_EDI-12	Sender GLN cannot be same as recipient GLN GLN відправника не може збігатись з GLN отримувача	Помилка виникає в методі create_and_send, коли клієнти відправляють документи самі собі
400	ERR_EDI-13	Branch uuid [%s] already revoked UUID [%s] гілки уже відкликано
400	ERR_EDI-14	COMDOC [019/021] not yet supported. COMDOC [019/021] ще не підтримується.	Помилка виникає тільки в 1му випадку: при спробі відправити цей підтип COMDOC методом create_and_send
400	ERR_EDI-15	Doc is not in open status Документ не в статусі - чернетка	Помилка виникає у випадках, коли клієнт хоче додати/видалити вкладення у документа не чернетки (CONDRA)
400	ERR_EDI-16	Document already revoked, current status: [%s] Документ уже відкликано, поточний статус: [%s]	Помилка виникає при спробі відправити тікет (прийняти COMDOC, підписати DOCINVOICE і т.д.), що протирічить логіці документообігу
400	ERR_EDI-17	Document already signed, current status: [%s] Документ уже підписаний, поточний статус: [%s]	Помилка виникає при спробі відправити тікет (прийняти COMDOC, підписати DOCINVOICE і т.д.), що протирічить логіці документообігу
400	ERR_EDI-18	Document already both signed, current status: [%s] Документ уже підписаний двома сторонами, поточний статус: [%s]	Помилка виникає при спробі відправити тікет (прийняти COMDOC, підписати DOCINVOICE і т.д.), що протирічить логіці документообігу
400	ERR_EDI-19	Document already сanceled, current status: [%s] Документ уже анульовано, поточний статус: [%s]	Помилка виникає при спробі відправити тікет (прийняти COMDOC, підписати DOCINVOICE і т.д.), що протирічить логіці документообігу
400	ERR_EDI-20	Document already repealed, current status: [%s] Документ уже скасовано, поточний статус: [%s]	Помилка виникає при спробі відправити тікет (прийняти COMDOC, підписати DOCINVOICE і т.д.), що протирічить логіці документообігу
400	ERR_EDI-21	Document already has repeal request, current status: [%s] Документ уже має запит на скасування, поточний статус: [%s]	Помилка виникає при спробі відправити тікет (прийняти COMDOC, підписати DOCINVOICE і т.д.), що протирічить логіці документообігу
400	ERR_EDI-22	Document has no repeal request, current status: [%s] Документ не має запиту на скасування, поточний статус: [%s]	Помилка виникає при спробі відправити тікет (прийняти COMDOC, підписати DOCINVOICE і т.д.), що протирічить логіці документообігу
400	ERR_EDI-23	Document’s repeal already rejected, current status: [%s] Скасування документа уже відхилено, поточний статус: [%s]	Помилка виникає при спробі відправити тікет (прийняти COMDOC, підписати DOCINVOICE і т.д.), що протирічить логіці документообігу
400	ERR_EDI-24	DocumentInvoice parties do not contain certificate’s EDRPOU: [%s] Сторони DocumentInvoice не містять ЄДРПОУ з сертифіката: [%s]
400	ERR_EDI-25	DocumentInvoice parties do not contain certificate’s DRFO: [%s] Сторони DocumentInvoice не містять ДРФО з сертифіката: [%s]
400	ERR_EDI-26	There is no EDRPOU/DRFO code in the signature certificate У сертифікаті підпису відсутні коди ЄДРПОУ/ДРФО
400	ERR_EDI-27	COMDOC parties do not contain certificate’s EDRPOU: [%s] Сторони COMDOC не містять ЄДРПОУ з сертифіката: [%s]
400	ERR_EDI-28	The signing key is not on a secure medium. Please select a different key and try again Ключ для підписання, що використовується, знаходиться не на захищеному носії. Виберіть, будь ласка, інший ключ і спробуйте ще раз
400	ERR_EDI-29	There is no signer position in the key. Please select a different key and try again У ключі немає посади підписувача. Виберіть, будь ласка, інший ключ і спробуйте ще раз
400	ERR_EDI-30	The document does not contain sender’s signatures. Change the settings of your signature module to create a signature online. Or contact technical support for advice. Документ не містить підписів відправника. Змініть налаштування свого модуля підписання для створення підпису онлайн. Або зверніться до служби технічної підтримки для консультації.
400	ERR_EDI-31	[signs] is empty [signs] порожній	Помилка виникає в роутах при роботі з тікетами (створення, відхилення документа, прийняття COMDOC і т.д.), у разі якщо клієнт користується застарілим способоv передачі тіла, використовуючи обєкт TicketRequestData і не передавши в json-і [signs]
400	ERR_EDI-32	Field [%s] is required Поле [%s] є обов’язковим	Помилка виникає тільки в роуті POST /api/eds/doc/archive, якщо в об’єкті DocumentStorageQuery не передано - direction або type, або docDate
400	ERR_EDI-33	Expected non-empty list of uuids Cписок uuid не може бути пустим	Помилка виникає тільки в роуті - /api/v2/eds/doc/content, якщо список uuid-ів порожній
400	ERR_EDI-34	The size of the list cannot be more than [%s] Розмір списку не може перевищувати [%s]	Помилка виникає тільки в роуті /api/v2/eds/doc/content, якщо в списку значень UUID більше ніж 50
400	ERR_EDI-35	Report’s start date [%s] cannot be more than end date [%s] Дата початку звіту [%s] не може перевищувати дату завершення [%s]	Помилка виникає в роутах формування звітів
400	ERR_EDI-36	Date range (from [%s] to [%s]) cannot be more than 31 days Діапазон дат (від [%s] до [%s]) не може перевищувати 31 день	Помилка виникає в роутах формування звітів
400	ERR_EDI-37	Report can be created based on only one parameter: sender OR recipient OR partner Звіт можна створити лише за одним параметром: sender OR recipient OR partner	Помилка виникає в роутах формування звітів
400	ERR_EDI-38	Content from request does not match original content, actual_hash:[%s] request_hash:[%s], actualContentHash Контент запиту не відповідає оригінальному контенту, actual_hash:[%s] request_hash:[%s], actualContentHash	Помилка виникає, якщо хеш контенту в eds не відповідають хешу контенту з тіла запиту (це про підписання документів у відповідь)
400	ERR_EDI-39	Signs count should be more than parent data signs count Кількість підписів повинна бути більшою, ніж у батьківській квитанції
400	ERR_EDI-40	[subjEDRPOUCode] from sign does not match any of [КодКонтрагента] or [ІПН] from XML [subjEDRPOUCode] із підпису не відповідає жодному з [КодКонтрагента] або [ІПН] із XML
400	ERR_EDI-41	Incorrect document family. One of [%s] is expected Некоректний family документа. Очікується один з наступних: [%s]
400	ERR_EDI-42	Handling sign failed - [%s] Не вдалося опрацювати підпис - [%s]	Помилка виникає при опрацюванні p7s, зазвичай ці помилки пов’язані з ІІТ бібліотекою
400	ERR_EDI-43	Ticket with transaction type [%s] not found Квитанцію з типом транзакції [%s] не знайдено	Помилка виникає в роутах при отриманні інформації по підписантам в тікеті
400	ERR_EDI-44	XSLT for document type [%s] not found XSLT для типу документа [%s] не знайдено	Не знайдено карту конвертації
400	ERR_EDI-45	Can’t define recipient GLN Неможливо визначити GLN одержувача	Не вдалось визначити отримувача при відправці DOCCORINVOICE
400	ERR_EDI-46	The document can only be signed by one party Документ може бути підписаний тільки однією стороною	Відправлений COMDOC містить поле «ОдностороннєПідписання»

Загальні помилки при роботі з API (всі сервіси EDIN)

Код відповіді	Індекс помилки	Текст помилки	Опис
400	ERR_CMN-1	Parameter(s) [%s] is(are) required Параметр(и) [%s] є обов’язковим(и)	Помилка виникає, якщо не передати обовязковий url-параметр (наприклад, doc_uuid)
400	ERR_CMN-2	Unknown or unsupported %s [%s] Непідтримуваний %s [%s]	Помилка виникає, якщо вказаний параметр не підтримується (наприклад, передавати response_type=xml, але доступні тільки - file, base64, bytes)
400	ERR_CMN-3	Parameter [%s] must have format format: [%s] Параметер [%s] повинен мати формат: [%s]	Помилка виникає, коли клієнт в url параметрі передав значення, в форматі, що не підтимується
400	ERR_CMN-4	Incorrect Content-Type in request, one of [%s] is expected Некоректний Content-Type. Очікується один з наступних:
400	ERR_CMN-5	Unsupported method [%s] Непідтримуваний метод [%s]
400	ERR_CMN-6	Expected [%s] file(s) in multipart/form data Очікується [%s] файл(и)ів у multipart/form data
400	ERR_CMN-7	Request body is empty Тіло запиту порожнє
400	ERR_CMN-7	Unknown gln: [%s] Невідомий gln: [%s]
400	ERR_CMN-8	Supported not more [%s] files per request Підтримується не більше [%s] файлів на запит
400	ERR_CMN-9	Exceeded max file name length Перевищено максимальну довжину імені файлу
400	ERR_CMN-10	Exceeded max file size - [%s] Перевищено максимальний розмір файлу - [%s]
400	ERR_CMN-11	Action not available, reason - [%s] Дія не доступна, причина - [%s]	Помилка виникає в різних випадках, наприклад, коли відправник документа CONDRA хоче її прийняти, але це може зробити тільки отримувач документа
400	ERR_CMN-12	Document with identifier [%s] not found Документ з ідентифікатором [%s] не знайдено
400	ERR_CMN-12	Chain with identifier [%s] not found Ланцюг з ідентифікатором [%s] не знайдено
400	ERR_CMN-13	Attachment with identifier [%s] not found Вкладення з ідентифікатором [%s] не знайдено
400	ERR_CMN-14	Ticket not found Квитанцію не знайдено
400	ERR_CMN-15	Package with identifier [%s] not found Пакет з ідентифікатором [%s] не знайдено
400	ERR_CMN-16	Incorrect format of field’s value Некоректний формат значення поля
400	ERR_CMN-17	error	Помилка в роботі процедури (БД)
400	ERR_CMN-18	Document body already exist Тіло документа вже існує	Дублювання тіла документа
400	ERR_CMN-19	Transformer for document type [%s] not found Перетворювач для типу документа [%s] не знайдено	Не вдалось знайти компонент для перетворення xml в json / json в xml і т.д.
400	ERR_CMN-20	Transforming error Помилка перетворення	Помилка при перетворенні, наприклад: при перетворенні xml в json, коли xml не відповідає специфікації документа
400	ERR_CMN-21	Malformed JSON Невірно сформований JSON	Неправильні дані / некоректний формат в полі json

Код помилки	Опис	Рекомендовані дії
500	Не класифікована помилка	У випадку, якщо Ви отримали у тілі відповіді подібний текст “Internal Server Error. Channel ID: 45b696af”, то зверніться за допомогою до нашої тех. підтримки. Якщо Ви отримали інший текст помилки, то прочитайте її і спробуйте зрозуміти. В багатьох випадках, проблема буде описана.
502	Сервер не відповідає	Перевірте ваше інтернет з’єднання. Якщо все гаразд, то спробуйте повторити раніше надісланий запит.
504	Тайм-аут отримання відповіді з сервера	У випадку надсилання запиту, що змінює дані (наприклад, підписання документа) ми рекомендуємо перевіряти виконання попереднього запиту (наприклад, чи був доданий підпис). З затримкою в 5 секунд надішліть запит для перевірки виконання Вашого попереднього запиту. Якщо Ваш попередній запит не виконався з будь-яких причин, повторіть його.
520	Сервісна помилка	Запит не був опрацьований нашими серверами. З затримкою в 5 секунд, повторіть Ваш запит.
521	Сервісна помилка	Запит не був опрацьований нашими серверами. З затримкою в 5 секунд, повторіть Ваш запит.
522	Сервісна помилка	Запит не був опрацьований нашими серверами. З затримкою в 5 секунд, повторіть Ваш запит.
523	Сервісна помилка	Запит не був опрацьований нашими серверами. З затримкою в 5 секунд, повторіть Ваш запит.
524	Сервісна помилка	Запит не був опрацьований нашими серверами. З затримкою в 5 секунд, повторіть Ваш запит.
525	Сервісна помилка	Запит не був опрацьований нашими серверами. З затримкою в 5 секунд, повторіть Ваш запит.
526	Сервісна помилка	Запит не був опрацьований нашими серверами. З затримкою в 5 секунд, повторіть Ваш запит.