Опис методів API, загальних для всіх сервісів

Метод авторизації на платформі

Token-Based Authorization

REQUEST

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

URL

 https://edo-v2.edin.ua

Метод запиту

POST

URL запиту

/api/authorization/hash

Headers

  

Content-Type

application/x-www-form-urlencoded

REQUEST

  

JSON Body

email (обов’язково) String - логін користувача

password (обов’язково) String - пароль користувача

Приклад запиту:

curl --location 'https://dev-oed.edin.ua/api/authorization/hash' \
--header 'l: xezpCrzv5fgk1kNRA/QUZg==' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data-raw 'email={{login}}&password={{password}}'
RESPONSE

В тілі відповіді, у JSON-форматі, передається «ключ сесії», необхідний для подальшої роботи.

У кожному наступному запиті (виклику методу) повинен бути присутнім HTTP-заголовок (Header) «Authorization», який для коректного виконання запитів має містити токен SID зі значенням, отриманим під час авторизації.

Приклад відповіді (JSON):

{"SID": "65daca25-74ba-4c85-8183-71b404a348c0"}

Тривалість сесії при бездіяльності користувача становить 20 хвилин.
Тобто ключ буде видалено через 20 хвилин, якщо користувач не буде активним (не надсилатиме HTTP-запити).

HTTP Basic Authentication

Також, при виконанні запитів, замість значення «SID» в HTTP-заголовку (Header) «Authorization», можливо відправляти серверу логін і пароль у якості базової аутентифікації (HTTP Basic Authentication).

При базовій аутентифікації клієнт разом із кожним запитом відправляє серверу логін і пароль. Ці дані передаються в заголовку запиту «Authorization» у вигляді Base64-коду.

Authorization: Basic base64_encode(login:password)

Так, наприклад, якщо логін і пароль admin, заголовок виглядатиме:

Authorization: Basic YWRtaW46YWRtaW4=

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

Код 400

Код відповіді

Індекс помилки

Текст помилки

Опис

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

Error occurred while retrieving information about the signer:

Помилка при отриманні інформації про підписанта:

  

400

ERR_CMN-19

Document body already exist

Тіло документа вже існує

Дублювання тіла документа

400

ERR_CMN-20

Transformer for document type [%s] not found

Перетворювач для типу документа [%s] не знайдено

Не вдалось знайти компонент для перетворення xml в json / json в xml і т.д.

400

ERR_CMN-21

Transforming error

Помилка перетворення

Помилка при перетворенні, наприклад: при перетворенні xml в json, коли xml не відповідає специфікації документа

400

ERR_CMN-22

Malformed JSON

Невірно сформований JSON

Неправильні дані / некоректний формат в полі json

400

ERR_CMN-23

ZIP format error:

Невірний формат ZIP:

  

400

ERR_CMN-24

UUID format error:

Невірний формат UUID:

  

400

ERR_CMN-25

Expected non-empty list of uuids

Cписок uuid не може бути пустим

  

400

ERR_CMN-26

The size of the list cannot be more than [%s]

Розмір списку не може перевищувати [%s]

  

400

ERR_CMN-27

The data is not signed or contains an incorrect signature

Дані не підписані або містять некорректний підпис

  

400

ERR_CMN-28

Content from request does not match original content, actual_hash:[%s] request_hash:[%s]

Контент запиту не відповідає оригінальному контенту, actual_hash:[%s] request_hash:[%s]

  

400

ERR_CMN-29

GLN from request [%s] should match sender’s GLN from body [%s]

GLN із запиту [%s] має збігатися з GLN відправника з тіла [%s]

  

400

ERR_CMN-30

The requested data was not found

Запитувані дані не знайдені

  

400

ERR_CMN-31

Field [%s] in request body is empty or invalid

Поле [%s] в тілі запиту порожнє або має недопустиме значення

  

400

ERR_CMN-32

Part [%s] in multipart/form-data is required

Частина [%s] в multipart/form-data є обов’язковою

  

400

ERR_CMN-32

File [%s] in multipart/form-data not found

Файл [%s] в multipart/form-data не знайдено

  

400

ERR_CMN-32

Field [%s] in post data is required

Поле [%s] в post data запиту не знайдено

  

400

ERR_CMN-33

At least one of parameters [%s] required

Необхідний принаймні один із параметрів [%s].

  

400

ERR_CMN-34

Unsupported parameter[%s]

Непідтримуваний параметр [%s].

  

Код 500

Код помилки

Опис

Рекомендовані дії

500

Не класифікована помилка

У випадку, якщо Ви отримали у тілі відповіді подібний текст “Internal Server Error. Channel ID: 45b696af”, то зверніться за допомогою до нашої тех. підтримки. Якщо Ви отримали інший текст помилки, то прочитайте її і спробуйте зрозуміти. В багатьох випадках, проблема буде описана.

502

Сервер не відповідає

Перевірте ваше інтернет з’єднання. Якщо все гаразд, то спробуйте повторити раніше надісланий запит.

504

Тайм-аут отримання відповіді з сервера

У випадку надсилання запиту, що змінює дані (наприклад, підписання документа) ми рекомендуємо перевіряти виконання попереднього запиту (наприклад, чи був доданий підпис). З затримкою в 5 секунд надішліть запит для перевірки виконання Вашого попереднього запиту. Якщо Ваш попередній запит не виконався з будь-яких причин, повторіть його.

520

Сервісна помилка

Запит не був опрацьований нашими серверами. З затримкою в 5 секунд, повторіть Ваш запит.

521

Сервісна помилка

Запит не був опрацьований нашими серверами. З затримкою в 5 секунд, повторіть Ваш запит.

522

Сервісна помилка

Запит не був опрацьований нашими серверами. З затримкою в 5 секунд, повторіть Ваш запит.

523

Сервісна помилка

Запит не був опрацьований нашими серверами. З затримкою в 5 секунд, повторіть Ваш запит.

524

Сервісна помилка

Запит не був опрацьований нашими серверами. З затримкою в 5 секунд, повторіть Ваш запит.

525

Сервісна помилка

Запит не був опрацьований нашими серверами. З затримкою в 5 секунд, повторіть Ваш запит.

526

Сервісна помилка

Запит не був опрацьований нашими серверами. З затримкою в 5 секунд, повторіть Ваш запит.

Опис сабстатусів документів для ETTN v3 (XDoc.extraFields.sub_status)

Товарно-транспортна накладна v3

sub_status_id

Status

Опис

Статус на платформі (web)

«-1»

  

Учасник документообігу (не Вантажовідправник) відправив «Попередню ТТН»

Попередня ТТН

«1»

PLANNED (IN_PROCESS)

Вантажовідправник підписав та відправив ТТН

Очікує на підписання перевізником

«6»

PICKUP (SIGNED_CARRIER_LOAD)

Перевізник підписав та відправив ТТН

Очікує на підписання вантажоодержувачем

«7»

ARRIVAL (SIGNED_CONSIGNEE)

Вантажоодержувач підписав та відправив ТТН

Підписано вантажоодержувачем 

«8»

CANCELED (CANCELED_CONSIGNOR)

Вантажовідправник відхилив ТТН

Відмовлено в підписанні вантажовідправником

«9»

CANCELED (CANCELED_CARRIER_LOAD)

Перевізник відхилив ТТН

Відмовлено в підписанні перевізником/водієм

«14»

CANCELED (CANCELED_MINTRANS)

ТТН відхилена через конвеєр подій (отримання документів з ЦБД)

Документ відхилено

«15»

CANCELED (CANCELED_STOP_ACT)

ТТН відхилена в результаті складання «Акта примусового завершення е-ТТН»

ТТН відхилено на підставі Акту примусового завершення ТТН

«16»

CANCELED (CANCELED_REJECT_ACT)

ТТН відхилена в результаті складання «Акта про відмову вантажити»

ТТН відхилено на підставі Акту про відмову вантажити 

«6» + extraFields.ettn_onstorage=1

ONSTORAGE

Проміжний склад підписав та відправив «Акт розвантаження на проміжному складі» та підписав і відправив оновлену ТТН

Очікує на підписання вантажоодержувачем.
(Роботу з ТТН заблоковано, оскільки вантаж перебуває на відповідальному зберіганні на проміжному складі. Можливість роботи буде відновлено після створення та завершення життєвого циклу Акта завантаження на проміжному складі.)
Акти v3 (всі види)

sub_status_id

Status

Опис

Статус на платформі (web)

«1»

PENDING_SIGNATURE

Акт підписаний ініціатором або наступним учасником до останнього учасника ЖЦ

Очікує на підписання отримувачем

«2»

SIGNED

Акт підписаний останнім учасником ЖЦ

Підписано всіма сторонами

«3»

CANCELED_CONSIGNOR

Акт відхилений Вантажовідправником

Відмовлено в підписанні вантажовідправником

«4»

CANCELED_CONSIGNEE

Акт відхилений Вантажоодержувач

Відмовлено в підписанні вантажоодержувачем 

«5»

CANCELED_CARRIER

Акт відхилений Перевізником

Відмовлено в підписанні перевізником/водієм

«6»

CANCELED_CUSTOMER

Акт відхилений Замовником

Відмовлено в підписанні замовником

«7»

CANCELED_CARRIER_SWITCH

Акт відхилений новим Перевізником

Відмовлено в підписанні новим перевізником

«8»

CANCELED_STORAGE

Акт відхилений Проміжним складом

Відмовлено в підписанні проміжним складом
Заявка на транспортування / Підтвердження заявки на транспортування

Ticket

exchange_status

sub_status_id

Опис

Статус на платформі (web)

T1

«000000000000000000000001»

«1»

Замовник відправив «Заявку на транспортування»

Перевізник відправив «Підтвердження заявки на транспортування»

Очікує на підписання замовником/перевізником

T1

«000000000000000000000001»

«2»

Перевізник підписав «Заявку на транспортування»

Замовник підписав «Підтвердження заявки на транспортування»

Підписано замовником/перевізником

T2

«000000000000000000000011»

«2»

Підписано з обох сторін

Підписано замовником/перевізником

T 11 2

«000000000000010000000011»

«3»

Може відправлятись на документ «Підтверджений з двох сторін» (2 Ticket) чи після «Відмови в анулюванні» (15 Ticket)

Надіслано запит на анулювання

T 12 2

«000000000000110000000011»

«4»

   Анульовано

T 13 1

«000000000001000000000001»

«5»

«Заявка на транспортування» відхилена Перевізником

Відмовлено в підписанні перевізником

T 14 1

«000000000010000000000001»

«6»

«Заявка на транспортування» відхилена Замовником

«Підтвердження заявки на транспортування» відхилено Перевізником

Підпис відкликано

T 15

«000000000100010000000011»

«2»

Може відправлятись у відповідь на «Запит на анулювання» (11 Ticket)

Відмовлено в анулюванні

Сабстатуси квитанцій/документів

Для комерційних документів (COMDOC):

Ticket

exchange_status

sub_status_id

Статус

Коментар

T0

«000000000000000000000000»

«0»

«Не підписано»

Інтегрована відправка не підписаного документа

T1

«000000000000000000000001»

«1»

«Потребує підписання отримувачем»

Підписано лише Відправником

T1

«000000000000000000000001»

«2»

«Потребує підписання відправником»

Підписано лише Отримувачем

T2

«000000000000000000000011»

«2»

«Підписано двома сторонами» / «Документ не потребує підписання»

Підписано з обох сторін в будь якому порядку / Відправлений документ містить поле «ОдностороннєПідписання» (підписується лише відправником)

T 11 1

«000000000000010000000001»

  

«Запит на анулювання»

В разі інтегрованої відправки COMDOC_19 (Запит на анулювання) до підписання документа COMDOC

T 11 2

«000000000000010000000011»

«3»

«Запит на анулювання»

Може відправлятись на COMDOC «Підтверджений з двох сторін» (2 Ticket) чи після «Відмови в анулюванні» (15 Ticket)

T 12 1

«000000000000110000000001»

  

«Прийняття запиту на анулювання» АБО

«Анульовано» в разі підписання вхідного інтегровано відправленого COMDOC_19 (Запит на анулювання) до підписання документа COMDOC

  

T 12 2

«000000000000110000000011»

«4»

«Анульовано»

  

T 13 1

«000000000001000000000001»

«5»

«Відмовлено в підписі»

  

T 14 1

«000000000010000000000001»

«6»

«Відкликано»

  

T 15

«000000000100010000000011»

«2»

«Відмовлено в анулюванні»

Може відправлятись у відповідь на «Запит на анулювання» (11 Ticket)
Для різних видів накладних (DOCUMENTINVOICE/DOCCORINVOICE):

Ticket

exchange_status

sub_status_id

Статус

Коментар

T0

«000000000000000000000000»

«0»

«Не підписано»

Інтегрована відправка не підписаного документа

T1

«000000000000000000000001»

«1»

«Потребує підписання отримувачем»

Підписано лише Відправником

T2

«000000000000000000000011»

«2»

«Підтверджено з двох сторін»

Підписано з обох сторін

T 13 1

«000000000001000000000001»

«5»

«Відмовлено в підписі»

  
Для «Заявки на транспортування»/«Підтвердження заявки на транспортування» (TRANSPORTATIONORDER):

Ticket

exchange_status

sub_status_id

Статус

Коментар

T1

«000000000000000000000001»

«1»

«Потребує підписання отримувачем»

Замовник відправив «Заявку на транспортування»

Перевізник відправив «Підтвердження заявки на транспортування»

T1

«000000000000000000000001»

«2»

«Потребує підписання відправником»

Перевізник підписав «Заявку на транспортування»

Замовник підписав «Підтвердження заявки на транспортування»

T2

«000000000000000000000011»

«2»

«Підтверджено з двох сторін»

Підписано з обох сторін

T 11 2

«000000000000010000000011»

«3»

«Запит на анулювання»

Може відправлятись на документ «Підтверджений з двох сторін» (2 Ticket) чи після «Відмови в анулюванні» (15 Ticket)

T 12 2

«000000000000110000000011»

«4»

«Анульовано»

  

T 13 1

«000000000001000000000001»

«5»

«Відмовлено в підписі»

«Заявка на транспортування» відхилена Перевізником

T 14 1

«000000000010000000000001»

«6»

«Підпис відкликано»

«Заявка на транспортування» відхилена Замовником

«Підтвердження заявки на транспортування» відхилено Перевізником

T 15

«000000000100010000000011»

«2»

«Відмовлено в анулюванні»

Може відправлятись у відповідь на «Запит на анулювання» (11 Ticket)