API сервісу Е-Сертифікати

Перелік методів API сервісу Е-Сертифікати

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

Для роботи з цими методами користувач повинен бути авторизованим.

Робота з сертифікатами
Створити сертифікат POST /api/ecs/certificate
Оновити сертифікат PUT /api/ecs/certificate
Отримати сертифікат GET /api/ecs/certificate
Видалити сертифікат DELETE /api/ecs/certificate
Архівувати / розархівувати сертифікат PUT /api/ecs/archive
Задати / змінити тип доступу до сертифіката PUT /api/ecs/access
Копіювати сертифікат PUT /api/ecs/copy
Знайти сертифікат / сертифікати POST /api/ecs/search
Додати (прив'язати) товари до сертифіката PUT /api/ecs/products
Масово завантажити сертифікати POST /api/ecs/certificates

Створити сертифікат з типом «Декларація виробника» (CERTDOC)

 POST /api/ecs/certdoc
Робота з вкладеннями до сертифікатів
Створити вкладення до сертифіката POST /api/ecs/body
Додати нові вкладення до сертифіката PUT /api/ecs/body
Отримати контент вкладення до сертифіката GET /api/ecs/body
Видалити всі вкладення до сертифіката DELETE /api/ecs/body
Отримати вкладення до сертифіката в PDF GET /api/ecs/body/download
Підписати вкладення до сертифіката

POST /api/ecs/certificate/sign
Отримати дані про підписання вкладення до сертифіката GET /api/ecs/certificate/sign
Робота з пов'язаними відвантаженнями
Отримати список відвантажень по сертифікату GET /api/ecs/certificate/shipments
Додати відвантаження в список відвантажень по сертифікату POST /api/ecs/certificate/shipments
Редагувати дані відвантаження PATCH /api/ecs/certificate/shipments
Видалити відвантаження з сертифікату DELETE /api/ecs/certificate/shipments

Опис помилок сервісу «Е-Сертифікати»

На цій сторінці наданий опис специфічних помилок сервісу «EDI Network». Опис загальних помилок для всіх сервісів EDIN можна  знайти за посиланням.

Опис загальних помилок сервісу «Е-Сертифікати»

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

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

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

Опис

400

ERR_CRT-1

Unknown certificate type: %s

Тип сертифіката некоректний: %s

Невідомий тип сертифіката при зміні типа доступа (PUT, «/api/ecs/access»)

400

ERR_CRT-2

Search query error: %s

Помилка пошукового запиту: %s

Некоректне тіло запита (POST, «/api/ecs/search»)

400

ERR_CRT-3

Certificate with UUID [%s] not found

Сертифікат із указаним UUID [%s] не знайдено

Сертифікат не знайдено (GET, «/api/ecs/certificate»)

400

ERR_CRT-4

Data validation errors detected

Виявлено помилки при обробленні даних

Помилки при опрацюванні сертифікатів, завантажених із excel (POST, «/api/ecs/certificates»)
Опис помилки при масовому завантаженні сертифікатів

Якщо в сертифікатах, що передаються буде допущена помилка, то Ви отримаєте відповідь про помилку в файлі, наприклад:

{
    "certificatesErrors":
    {
        "2":
        [
            {
                "errorType": 1,
                "columnName": "Тип сертификату"
            },
            {
                "errorType": 2,
                "columnName": "Тип сертификату"
            },
            {
                "errorType": 1,
                "columnName": "Номер сертифікату"
            },
            {
                "errorType": 1,
                "columnName": "Дата видачі"
            },
            {
                "errorType": 1,
                "columnName": "Вид сертифікату"
            },
            {
                "errorType": 2,
                "columnName": "Вид сертифікату"
            },
            {
                "errorType": 1,
                "columnName": "Дата закінчення дії",
                "cause": "Вид сертифікату = 1"
            },
            {
                "errorType": 1,
                "columnName": "Номер партії",
                "cause": "Вид сертифікату = 2"
            },
            {
                "errorType": 1,
                "columnName": "Дата початку дії"
            },
            {
                "errorType": 1,
                "columnName": "Назва файлу"
            },
            {
                "errorType": 2,
                "columnName": "Назва файлу",
                "allowedValues": "[pdf, jpg, jpeg, png, tiff]",
                "fileName": "filename.txt"
            },
            {
                "errorType": 3,
                "columnName": "Назва файлу",
                "fileName": "filename.pdf"
            },
            {
                "errorType": 4,
                "columnName": "Назва файлу",
                "fileName": "filename.pdf"
            }
        ]
    },
    "productsErrors":
    {
        "2":
        [
            {
                "errorType": 1,
                "columnName": "Номер сертифікату"
            }
        ]
    },
    "createdCertificates":
    [],
    "existedCertificates":
    [],
    "certsCount": 0,
    "productsCount": 0
}

Опис параметрів помилки

Поле

Опис

certificatesErrors/productsErrors

об’єкт; починається з номера рядка сертифіката / рядка тварної позиції (відповідно), де була допущена помилка. Містить параметри:

  • errorType - тип помилки:

    • 1 - Незаповнене обов’язкове поле, для цього значення помилка може містити поле cause (причина чому воно має бути обов’язкове, як у випадку з Дата закінчення дії або Номер партії;

    • 2 - Некоректне значення поля, для цього поля також є поле allowedValues, це для помилки з Ім’ям файлу; для цього значення помилка може містити поле fileName;

    • 3 - Файл з іменем файла вказаним в колонці Імя файлу не знайдено в zip-архіві; для цього значення помилка може містити поле fileName;

    • 4 - Файл з іменем файла вказаним в колонці Імя файлу занадто великий; для цього значення помилка може містити поле fileName.

  • columnName - назва колонки;

createdCertificates

масив; номера створених сертифікатів

existedCertificates

масив; номера існуючих сертифікатів

certsCount - кількість сертифікатів (рядків на 1-му листі xls/xlsx-файлу)

  

productsCount - кількість товарних позицій (рядків на 2-му листі xls/xlsx-файлу)

Видалити відвантаженя з сертифікату DELETE /api/ecs/certificate/shipments

За допомогою цього методу можна із сертифікату видалити відвантаження по їхньому id.

REQUEST

URL

  

Метод запиту

DELETE

URL запиту

/api/ecs/certificate/shipments

URL параметри

gln (обов’язково) String - GLN власної Компанії

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

application/json

REQUEST


JSON Body

В тілі запиту передається JSON масив ідентифікаторів відвантажень.

 

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

 

[11,7]

RESPONSE

Код сервера 200 (ok).

Редагувати дані відвантаження PATCH /api/ecs/certificate/shipments

REQUEST

URL

  

Метод запиту

PATCH

URL запиту

/api/ecs/certificate/shipments

URL параметри

gln (обов’язково) String - GLN власної Компанії

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

application/json

REQUEST


JSON Body

В тілі запиту передається JSON масив параметрів відвантаження (об'єкт XCertificateShipment).

 

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

 

[{"id":11,"creatorId":13202937,"number":"shipment_11","date":1740269800,"buyer":"9864065750135"},{"id":7,"creatorId":13202937,"number":"shipment_7","date":1740169800,"buyer":"9864065750119"}]

 

RESPONSE

Код сервера 200 (ok).

Додати відвантаження в список відвантажень по сертифікату POST /api/ecs/certificate/shipments

REQUEST

URL

  

Метод запиту

POST

URL запиту

/api/ecs/certificate/shipments

URL параметри

gln (обов’язково) String - GLN власної Компанії;

uuid (обов'язково) - сертифіката, обовязковий
limit (необовязково) - якщо не передається, значення за замовчуванням 20
offset (необовязково) - якщо не передається, значення за замовчуванням 0

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

application/json

REQUEST


JSON Body

В тілі запиту передається JSON масив параметрів відвантаження (об'єкт XCertificateShipment).

 

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

 

[{"number":"shipment_1","date":"1740169800","buyer":"9864065750119"},{"number":"shipment_4","date":"1740336908","buyer":"9864065750148"}]

RESPONSE

Код сервера 200 (ok).

Отримати список відвантажень по сертифікату GET /api/ecs/certificate/shipments

REQUEST

URL

  

Метод запиту

GET

URL запиту

/api/ecs/certificate/shipments

URL параметри

gln (обов’язково) String - GLN власної Компанії;

uuid (обовязково) - ідентифікатор сертифіката
limit (необовязково) - якщо не передали, значення 20
offset (необовязково) - якщо не передали, значення 0

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

application/json

RESPONSE

У відповідь отримується JSON масив об'єктів з даними відвантажень, пов'язаних з обраним сертифікатом (об'єкти XCertificateShipment).

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

[{"id":9,"creatorId":13202937,"number":"shipment_2","date":1740369800,"buyer":"9864065750117"},{"id":15,"creatorId":13202937,"number":"shipment_3","date":1740269800,"buyer":"9864065750135"},{"id":13,"creatorId":13202937,"number":"shipment_1","date":1740169800,"buyer":"9864065750119"}]

Отримати вкладення до сертифіката в PDF GET /api/ecs/body/download

REQUEST

URL

  

Метод запиту

GET

URL запиту

/api/ecs/body/download

URL параметри

gln (обов’язково) String - GLN власної Компанії;

uuid (обов’язково) UUID - унікальний ідентифікатор сертифіката

body_type (обов’язково) int - тип тіла:

  • 1 - вкладення до сертифіката;

  • 2 - base64 контент без підписів/печаток;
  • 3- sign, base64 тіло підпису

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

application/pdf

RESPONSE

У тілі відповіді передається

Видалити всі вкладення сертифіката DELETE /api/ecs/body

REQUEST

URL

  

Метод запиту

DELETE

URL запиту

/api/ecs/body

URL параметри

gln (обов’язково) String - GLN власної Компанії;

uuid (обов’язково) UUID - унікальний ідентифікатор сертифіката

body_type (обов’язково) int - тип тіла:

  • 1 - вкладення до сертифіката

Headers

  

Authorization

SID - токен, отриманий при авторизації

RESPONSE

Код сервера 200 (ok).

Отримати контент вкладення до сертифіката GET /api/ecs/body

REQUEST

URL

  

Метод запиту

GET

URL запиту

/api/ecs/body

URL параметри

gln (обов’язково) String - GLN власної Компанії;

uuid (обов’язково) UUID - унікальний ідентифікатор сертифіката

body_type (обов’язково) int - тип тіла:

  • 1 - вкладення до сертифіката

Headers

  

Authorization

SID - токен, отриманий при авторизації

RESPONSE

У тілі відповіді передається контент сформованого pdf файлу з вкладеннями у вигляді base64 рядка.

Додати нові вкладення до сертифіката PUT /api/ecs/body

Максимальний розмір файлу для завантаження - 7,5 МБ

REQUEST

URL

  

Метод запиту

POST

URL запиту

/api/ecs/body

URL параметри

gln (обов’язково) String - GLN власної Компанії;

uuid (обов’язково) UUID - унікальний ідентифікатор сертифіката

body_type (обов’язково) int - тип тіла:

  • 1 - вкладення до сертифіката

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

multipart/form-data

REQUEST

  

Form-data

В тілі запиту передаються файли вкладень в форматі PDF, JPG, JPEG, PNG, TIFF. Всі файли, що передаються будуть автоматично об’єднані в один PDF файл.

 

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

 

-----------------------------28001198861666343170695798896
Content-Disposition: form-data; name="files[]"; filename="istockphoto-1154370446-612x612.png"
Content-Type: image/png

(data)

-----------------------------28001198861666343170695798896
Content-Disposition: form-data; name="files[]"; filename="photo-1518020382113-a7e8fc38eac9.jpeg"
Content-Type: image/jpeg

(data)

-----------------------------28001198861666343170695798896--

RESPONSE

У тілі відповіді передається контент сформованого pdf файлу з вкладеннями у вигляді base64 рядка.

Створити вкладення до сертифікату POST /api/ecs/body

Максимальний розмір файлу для завантаження - 7,5 МБ

REQUEST

URL

  

Метод запиту

POST

URL запиту

/api/ecs/body

URL параметри

gln (обов’язково) String - GLN власної Компанії;

uuid (обов’язково) UUID - унікальний ідентифікатор сертифіката

body_type (обов’язково) int - тип тіла:

  • 1 - вкладення до сертифіката

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

multipart/form-data

REQUEST

  

Form-data

В тілі запиту передаються файли вкладень в форматі PDF, JPG, JPEG, PNG, TIFF. Всі файли, що передаються будуть автоматично об’єднані в один PDF файл.

 

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

-----------------------------28001198861666343170695798896
Content-Disposition: form-data; name="files[]"; filename="istockphoto-1154370446-612x612.png"
Content-Type: image/png

(data)

-----------------------------28001198861666343170695798896
Content-Disposition: form-data; name="files[]"; filename="photo-1518020382113-a7e8fc38eac9.jpeg"
Content-Type: image/jpeg

(data)

-----------------------------28001198861666343170695798896--

RESPONSE

У тілі відповіді передається контент сформованого pdf файлу з вкладеннями у вигляді base64 рядка.

Створити сертифікат з типом «Декларація виробника» (CERTDOC) POST /api/ecs/certdoc

REQUEST

URL

  

Метод запиту

POST

URL запиту

/api/ecs/certdoc

URL параметри

gln (обов’язково) String - GLN власної Компанії

publish (необов’язково) Boolean- ознака публікації сертифікату при створенні:

  • true - значення за замовчуванням, сертифікат публікується,

  • false - сертифікат створюється в чернетках

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

multipart/form-data

REQUEST

  

Form-data

В тілі запиту передається XML файл сертифіката.

RESPONSE

У тілі відповіді передається унікальний ідентифікатор (UUID) створеного сертифіката, наприклад:

 55ef04b2-281e-4fca-bb67-d48fe88ae74f.

Масово завантажити сертифікати POST /api/ecs/certificates

Максимальний розмір файлу для завантаження - 7,5 МБ

REQUEST

URL

  

Метод запиту

POST

URL запиту

/api/ecs/certificates

URL параметри

gln (обов’язково) String - GLN власної Компанії

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

multipart/form-data

REQUEST

  

JSON Body

В тілі запиту передається zip-файл, що містить файли-вкладення (в форматі PDF, JPG, JPEG, PNG, TIFF) та заповнений xls/xlsx шаблон з зазначеними назвами файлів-вкладень.

Приклад передаваємого zip знаходиться у вкладенні до цієї сторінки (ліва бокова панель).

RESPONSE

У тілі відповіді передаються дані завантажених сертифікатів (масив об’єктів XCertificate).

Якщо в сертифікатах, що передаються, буде допущена помилка, то Ви отримаєте відповідь про помилку в файлі.

Додати (прив’язати) товари до сертифіката PUT /api/ecs/products

Якщо продукт уже прив’язаний до сертифіката і в тілі передано його ідентифікатор (XCertificateProduct.id), то дані товару будуть оновлені, в іншому випадку буде створено новий товар.

REQUEST

URL

  

Метод запиту

PUT

URL запиту

/api/ecs/products

URL параметри

gln (обов’язково) String - GLN власної Компанії;

uuid (обов’язково) UUID - унікальний ідентифікатор сертифіката

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

application/json

REQUEST

  

JSON Body

В тілі запиту методу передаються дані товарів, що прив’язуються до сертифіката (масив об’єктів XCertificateProduct).

RESPONSE

Код сервера 200 (ok).

Знайти сертифікат/-ти POST /api/ecs/search

REQUEST

URL

  

Метод запиту

POST

URL запиту

/api/ecs/search

URL параметри

gln (обов’язково) String - GLN власної Компанії

owner_gln (необов’язково) String - GLN Компанії-Власника сертифікату

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

application/json

REQUEST

  

JSON Body

В тілі запиту методу передаються дані для фільтрації (об’єкт XQueryCertificates)

RESPONSE

В тілі відповіді передаються дані про сертифікати.

Копіювати сертифікат PUT /api/ecs/copy

REQUEST

URL

  

Метод запиту

PUT

URL запиту

/api/ecs/copy

URL параметри

gln (обов’язково) String - GLN власної Компанії;

uuid (обов’язково) UUID - унікальний ідентифікатор сертифіката

company_id (опціонально) long - ідентифікатор компанії, від якої здійснюється запит

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

application/json

RESPONSE

Код сервера 200 (ok).

Задати/змінити тип доступу до сертифіката PUT /api/ecs/access

REQUEST

URL

  

Метод запиту

PUT

URL запиту

/api/ecs/access

URL параметри

gln (обов’язково) String - GLN власної Компанії;

uuid (обов’язково) UUID - унікальний ідентифікатор сертифіката (можливо передавати кілька в одному запиті)

type (обов’язково) String - тип доступу, можливі значення:

  • private - обмежений доступ

  • public - публічний доступ

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

application/json

REQUEST

  

JSON Body

Тіло очікується лише при type=private: тіло запиту в форматі Map<Long, Boolean>, де ключ - це intGlnID кому відкрито доступ, а значення true/false - чи буде дозволено даному intGlnID репостити цей сертифікат комусь іще.

 

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

 

1
[[13203393,false],[13203397,false]]

RESPONSE

Код сервера 200 (ok).

Архівувати / розархівувати сертифікат PUT /api/ecs/archive

Дія «архівувати» / «розархівувати» залежить від того, де перебуває сертифікат до виконання метода:

REQUEST

URL

  

Метод запиту

PUT

URL запиту

/api/ecs/archive

URL параметри

gln (обов’язково) String - GLN власної Компанії;

uuid (обов’язково) UUID - унікальний ідентифікатор сертифіката

Headers

  

Authorization

SID - токен, отриманий при авторизації

RESPONSE

Код сервера 200 (ok).

Видалити сертифікат DELETE /api/ecs/certificate

REQUEST

URL

  

Метод запиту

DELETE

URL запиту

/api/ecs/certificate

URL параметри

gln (обов’язково) String - GLN власної Компанії;

uuid (обов’язково) UUID - унікальний ідентифікатор сертифіката

Headers

  

Authorization

SID - токен, отриманий при авторизації

RESPONSE

Код сервера 200 (ok).

Отримати сертифікат GET /api/ecs/certificate

REQUEST

URL

  

Метод запиту

GET

URL запиту

/api/ecs/certificate

URL параметри

gln (обов’язково) String - GLN власної Компанії;

uuid (обов’язково) UUID - унікальний ідентифікатор сертифіката

Headers

  

Authorization

SID - токен, отриманий при авторизації

RESPONSE

В тілі відповіді передаються дані про сертифікат.

Оновити сертифікат PUT /api/ecs/certificate

REQUEST

URL

  

Метод запиту

PUT

URL запиту

/api/ecs/certificate

URL параметри

gln (обов’язково) String - GLN власної Компанії

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

application/json

REQUEST

  

JSON Body

В тілі запиту (json) передається об’єкт з даними сертифіката.

RESPONSE

Код сервера 200 (ok).

Створити сертифікат POST /api/ecs/certificate

REQUEST

URL

  

Метод запиту

POST

URL запиту

/api/ecs/certificate

URL параметри

gln (обов’язково) String - GLN власної Компанії

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

application/json

REQUEST

  

JSON Body

В тілі запиту (json) передається об’єкт з даними сертифіката.

RESPONSE

У тілі відповіді передається унікальний ідентифікатор (UUID) створеного сертифіката, наприклад: 55ef04b2-281e-4fca-bb67-d48fe88ae74f.

Підписати вкладення до сертифіката POST /api/ecs/certificate/sign

Для підпису доступні тільки сертифікати в стані чернетки із завантаженим вкладенням. Підписувати може тільки користувач з GLN, який створив даний сертифікат.

REQUEST

URL

  

Метод запиту

POST

URL запиту

/api/ecs/certificate/sign

URL параметри

gln (обов’язково) String - GLN власної Компанії;

uuid (обов’язково) UUID - унікальний ідентифікатор сертифіката

Headers

  

Authorization

SID - токен, отриманий при авторизації

Content-Type

application/octet-stream

REQUEST

  

JSON Body

В тілі запиту методу передається файл підпису p7s в base64 форматі.

RESPONSE

Код сервера 200 (ok).

Отримати дані про підписання вкладення до сертифіката GET /api/ecs/certificate/sign

REQUEST

URL

  

Метод запиту

GET

URL запиту

/api/ecs/certificate/sign

URL параметри

 

gln (обов’язково) String - GLN власної Компанії;

uuid (обов’язково) - UUID, унікальний ідентифікатор сертифіката

Headers

  

Authorization

SID - токен, отриманий при авторизації

RESPONSE

В тілі відповіді (json) передається інформація про підписантів (масив об’єктів ExEndUserSignInfo ).