Загальний опис API 2.0
Host Dev
dev.e-check.com.ua

Для початку роботи з API потрібно:
Зареєструватись в Е-чек
Зареєструвати касу.
Отримати apikey для роботи з open-api.
Обробка помилок -

Для виклику open-api необхідно мати ключ для коректного доступу. Ключ для користувача видається за запитом.
Headers
apikey
string*
device
string

1.1 Початок роботи
Для подальшої роботи з open-api необхідно отримати sign-token-id. Для цього необхідно викликати POST - https://{host}/v2/auth/set-sign-token

Body
file
binary*
Файловий ключ
caId
string*
КНЕДП

Request

Response

Після отримання sign-token-id можна перейти до відкриття зміни.
Зміна
1.2 Відкрити зміну
Для відкриття зміни необхідно викликати POST - https://{host}/v2//shift/open

Body
publicKey
string*
Публічний ключ яким потрібно хешувати пароль для файлового ключа
keyHash
string*
Результат хешування пароля
signTokenId
uuid*
Ідентифікатор отриманий на попередньому етапі

Request

Response

Після відкриття зміни ви отримаєте дані по цій зміні.
1.3 Закрити зміну
Для закриття зміни необхідно викликати POST - https://{host}/v2//shift/close

publicKey
string*
Публічний ключ яким потрібно хешувати пароль для файлового ключа
keyHash
string*
Результат хешування пароля
signTokenId
uuid*
Ідентифікатор отриманий на попередньому етапі
shiftId
uuid*
Ідентифікатор зміни яку треба закрити

Request

Response

Після відкриття зміни ви отримаєте дані по цій зміні.
Чеки
1.4 Створення префіскалізованного чеку
Для створення префіскалізованного чеку необхідно викликати POST - https://{host}/v2//receipt/draft

Body
shiftId
uuid*
Ідентифікатор зміни
productOutOfTheBoard
Array()*
Масив продуктів
name
string*
Назва продукту
quantity
number*
Кількість товару. Залежить від шкали вимірювання (measurementId)
price
number*
ціна
tx
string*
акциз
measurementId
int*
Ідентифікатор шкали вимірювання. Повний список тут

Request

Response

Після успішного виконання методу ви отримаєте ідентифікатор чека.

1.5 Фіскалізація чека
Для фіскалізації чека необхідно викликати метод POST - https://{host}/v2//receipt/sell

Body
id
Ідентифікатор чека

signTokenId
uuid*
Ідентифікатор токена
publicKey
uuid*
Публічний ключ яким потрібно хешувати пароль для файлового ключа
keyHash
string*
Результат хешування пароля
paymentGroupsList
Array()

paymentType
string*
CASH або NON_CASH
paymentTypeId
number*
Перелік тип оплат тут
internalPaymentTypeId
number*
Перелік внутрішніх типів оплат тут
cash
number (default = 0)
готівка

Request

Response

Після успішної операції ви отримаєте ідентифікатор чеку та лінку на pdf файл чеку.
1.6 Скасування чека
Для скасування чека необхідно викликати DELETE - https://{host}/v2//receipt/sell/{checkId}

Params
checkId
uuid*
Ідентифікатор чека

Body
signTokenId
uuid*
Ідентифікатор токена
shiftId
uuid*
Ідентифікатор зміни
publicKey
string*
Публічний ключ яким потрібно хешувати пароль для файлового ключа
keyHash
string*
Результат хешування пароля

Request

Response
Після відміни чека ви отримаєте ідентифікатор даного чека.
1.7 Актуальний чек(часткова відміна)
Даний метод необхідний для часткової відміни чеку. Даний метод повертає перелік товарів які можна відмінити у конкретного чека

GET - https://{host}/v2//receipt/get-actual-check/{checkId}

Params
checkId
uuid*
Ідентифікатор чека

У відповідь ви отримаєте перелік товарів які можна відмінити

Response
{
“success”: true,
“data”: [
{
“productCode”: null,
“barCode”: null,
“uktzed”: null,
“exciseTaxStamp”: null,
“name”: “Яблука (перший гатунок)”,
“initialSum”: {
“doubleAmount”: 15,
“longAmount”: {
“p_1”: 1500,
“q_1”: 0
},
“stringAmount”: “15.00”
},
“resultSum”: {
“doubleAmount”: 15,
“longAmount”: {
“p_1”: 1500,
“q_1”: 0
},
“stringAmount”: “15.00”
},
“quantity”: {
“doubleAmount”: 3,
“longAmount”: {
“p_1”: 3000,
“q_1”: 0
},
“stringAmount”: “3.000”
},
“originalQuantity”: {
“doubleAmount”: 3,
“longAmount”: {
“p_1”: 3000,
“q_1”: 0
},
“stringAmount”: “3”
},
“price”: {
“doubleAmount”: 5,
“longAmount”: {
“p_1”: 500,
“q_1”: 0
},
“stringAmount”: “5.00”
},
“initialTax”: {
“tx”: “1”,
“taxCalculationsList”: [
{
“taxType”: {
“key”: “1”,
“letterKey”: “А”,
“value”: 20,
“type”: “VAT”,
“title”: “ПДВ_А”,
“valueInText”: “20.00%”,
“formula”: "(##PRICE##/(100+##VAT##)##VAT##)",
“parsedFormula”: “(10.0/(100+20.0)20.0)"
},
“calculationsItem”: {
“valueInPercentage”: 20,
“valueSum”: {
“doubleAmount”: 2.5,
“longAmount”: {
“p_1”: 250,
“q_1”: 0
},
“stringAmount”: “2.50”
}
}
}
],
“taxesSum”: {
“doubleAmount”: 2.5,
“longAmount”: {
“p_1”: 250,
“q_1”: 0
},
“stringAmount”: “2.50”
},
“taxInPriceType”: {
“e3_1”: “INCLUDED”,
“f3_1”: 0,
“value”: 0
},
“taxCalculationAlgorithm”: {
“e3_1”: “VAT_NO_ADDITIONAL_FEE”,
“f3_1”: 0,
“value”: 0
}
},
“resultTax”: {
“tx”: “1”,
“taxCalculationsList”: [
{
“taxType”: {
“key”: “1”,
“letterKey”: “А”,
“value”: 20,
“type”: “VAT”,
“title”: “ПДВ_А”,
“valueInText”: “20.00%”,
“formula”: "(##PRICE##/(100+##VAT##)##VAT##)”,
“parsedFormula”: "(10.0/(100+20.0)20.0)"
},
“calculationsItem”: {
“valueInPercentage”: 20,
“valueSum”: {
“doubleAmount”: 2.5,
“longAmount”: {
“p_1”: 250,
“q_1”: 0
},
“stringAmount”: “2.50”
}
}
}
],
“taxesSum”: {
“doubleAmount”: 2.5,
“longAmount”: {
“p_1”: 250,
“q_1”: 0
},
“stringAmount”: “2.50”
},
“taxInPriceType”: {
“e3_1”: “INCLUDED”,
“f3_1”: 0,
“value”: 0
},
“taxCalculationAlgorithm”: {
“e3_1”: “VAT_NO_ADDITIONAL_FEE”,
“f3_1”: 0,
“value”: 0
}
},
“initialSumExcludingVatAndFees”: {
“doubleAmount”: 12.5,
“longAmount”: {
“p_1”: 1250,
“q_1”: 0
},
“stringAmount”: “12.50”
},
“resultSumExcludingVatAndFees”: {
“doubleAmount”: 12.5,
“longAmount”: {
“p_1”: 1250,
“q_1”: 0
},
“stringAmount”: “12.50”
},
“returningType”: {
“e3_1”: “PRODUCT_RETURNING_OR_COMPENSATION”,
“f3_1”: 0,
“value”: 0
},
“discount”: null,
“haveTouristFee”: false,
“touristFeeSum”: null,
“isOutOfBoard”: true,
“productsSortIndex”: 1,
“measurementDto”: {
“id”: 2,
“title”: “кг”,
“precision”: 3
},
“productId”: “c23c46d2-d1ef-4304-83ae-f2aa40adf67f”
}
],
“error”: null
}
1.8 Часткова відміна чеку
Для часткової відміни чеку необхідно викликати POST - /receipt/return
Body
checkId
uuid
Ідентифікатор чеку для якого робимо часткову відміну
signTokenId
uuid
Ідентифікатор токена
keyHash
string*
Результат хешування пароля
productsListIds
Array(uuid)*
Ідентифікатори товарів, що відмінені, отримані із попереднього запиту

Request

Response

1.9 Отримання чеку по id
Для отримання інформації по чеку необхідно викликати наступний метод GET - https://{host}/v2/receipt/sell/{checkId}

Params
checkId
uuid*
Ідентифікатор чеку

Response
{
“success”: true,
“data”: {
“rawData”: “Інформація про чек”
},
“error”: null
}

Успішна відповідь поверне json з інформацію по чеку.

У разі якщо чек не знайдено буде повернено null

{
“success”: true,
“data”: {
“rawData”: null
},
“error”: null
}
1.10 Отримання переліку чеків
Для отримання переліку чеків необхідно викликати метод GET - https://{host}/v2/export/checks

Queries (фільтра)
sort
string
Тип сортування asc/desc
page
string
Номер сторінки
pageSize
string
Кількість чеків на сторінці
shiftId
string
Ідентифікатор
cashRegisterId
string
Ідентифікатор каси
startDate
string (timestamp)
Чеки створені починаючи з дати
finishDate
string (timestamp)
Чеки створені по дату
typeAction
string
Тип чека. Повний список тут

Response
У відповідь на запит отримаєте масив чеків
{
“success”: true,
“data”: [
{
“id”: “16d94cc8-c2ea-40a6-a7b4-19e6a0031c38”,
“shiftId”: “31ca19bf-bc43-42da-8a62-c2af5ea06410”,
“companyId”: “839”,
“cashRegisterId”: “36423”,
“workerId”: “1203”,
“type”: “SELLING”,
“status”: “DONE”,
“hashMac”: “483bdce1f03f5686fbbc51a9f79f97c37c4e0c52e86597d95f324171e3f27302”,
“fiscalisationNumber”: “m9gOw6mgSvE”,
“fiscalisationTime”: 1695496813126,
“creationTime”: 1695496807907,
“isOffline”: false,
“additionalInfo”: null,
“totalSum”: 290,
“workerLastName”: “на общей без НДС”,
“workerFirstName”: “ЮЛ”,
“cashRegisterName”: “Е_ЧЕК_42039(1)”,
“createdAt”: 1695496823476,
“updatedAt”: 1695496823476,
“countCRId”: 1
}
],
“error”: null
}
Співробітники
1.11 Створення
Для додавання співробітника необхідно викликати метод POST - https://{host}/v2/worker/create

Body
name
string*
Ім’я
passwordHash
string*
Пароль касира
surname
string*
Прізвище
roleId
number*
Роль співробітника. Усі ролі співробітників прописані тут
phone
string*
Номер телефону
cashRegisterIds
number[]*
Ідентифікатори кас до яких відноситься співробітник

Request
{
“name”: “name”,
“passwordHash”: “1234”,
“surname”: “surname”,
“roleId”: “4”,
“phone”: “+380900000000”,
“cashRegisterIds”: [37032]
}

Response
{
“success”: true,
“data”: {
“id”: 27,
“passwordHash”: “1234”,
“name”: “name”,
“surname”: “surname”,
“photoUrl”: null,
“photoUrlPreview”: null,
“phone”: “+380900000000”,
“roleId”: 4,
“companyId”: 839,
“numberSms”: 3,
“keyTax”: null,
“keyStorePassword”: null,
“keyType”: null,
“status”: null,
“email”: null,
“newApplication”: false,
“loginAttemptsCount”: null,
“lastAttemptIp”: null,
“openId”: null,
“cashRegisterWorker”: null
},
“error”: null
}

1.12 Редагування
Для редагування співробітника необхідно викликати метод PATCH - https://{host}/v2/worker/update/{workerId}

Params
workerId
string*
Ідентифікатор співробітника

Body
name
string
Ім’я
passwordHash
string
Пароль касира
surname
string
Прізвище
roleId
number
Роль співробітника. Усі ролі співробітників прописані тут
phone
string
Номер телефону
cashRegisterIds
number[]
Ідентифікатори кас до яких відноситься співробітник

Request
{
“name”: “udpated”,
“surname”: “updated”
}

Response
{
“success”: true,
“data”: {
“id”: 27,
“passwordHash”: “1234”,
“name”: “udpated”,
“surname”: “updated”,
“photoUrl”: null,
“photoUrlPreview”: null,
“phone”: “+380900000000”,
“roleId”: 4,
“companyId”: 839,
“numberSms”: 3,
“keyTax”: null,
“keyStorePassword”: null,
“keyType”: null,
“status”: null,
“email”: null,
“newApplication”: false,
“loginAttemptsCount”: null,
“lastAttemptIp”: null,
“openId”: null,
“cashRegisterWorker”: null
},
“error”: null
}

1.13 Видалення
Для видалення співробітника необхідно викликати метод DELETE - https://{host}/v2/worker/delete/{workerId}

Params
workerId
string*
Ідентифікатор співробітника

Response
{
“success”: true,
“data”: {
“status”: true
},
“error”: null
}

1.14 Отримання по ідентифікатору
Для отримання інформації по співробітнику необхідно викликати метод GET- https://{host}/v2/worker/get-by-id/{workerId}

Params
workerId
string*
Ідентифікатор співробітника

Response

{
“success”: true,
“data”: {
“id”: 18,
“passwordHash”: “111”,
“name”: “Тестовый”,
“surname”: “Пользователь”,
“photoUrl”: “”,
“photoUrlPreview”: “”,
“phone”: “380987789982”,
“roleId”: 4,
“companyId”: 839,
“numberSms”: null,
“keyTax”: null,
“keyStorePassword”: null,
“keyType”: null,
“status”: null,
“email”: null,
“newApplication”: false,
“loginAttemptsCount”: null,
“lastAttemptIp”: null,
“openId”: null,
“cashRegisterWorker”: null
},
“error”: null
}

1.15 Отримання переліку
Для отримання інформації по співробітнику необхідно викликати метод GET- https://{host}/v2/worker/get-list

Response
{
“success”: true,
“data”: [
{
“id”: 19,
“passwordHash”: “111”,
“name”: “test2”,
“surname”: “test2”,
“photoUrl”: “test2”,
“photoUrlPreview”: “test2”,
“phone”: “+3888”,
“roleId”: 4,
“companyId”: 839,
“numberSms”: null,
“keyTax”: null,
“keyStorePassword”: null,
“keyType”: null,
“status”: null,
“email”: null,
“newApplication”: false,
“loginAttemptsCount”: null,
“lastAttemptIp”: null,
“openId”: null,
“cashRegisterWorker”: null
},
],
“error”: null
}

Приклади запитів
2.1 Fiscalization check
Body
{
“id”: “7eae5195-d517-4dad-93ef-a751e2e6c593”,
“signTokenId”: “49f42fa8-4701-40e9-bd98-d7a0499295b1”,
“publicKey”: “…”,
“keyHash”: “…”,
“paymentGroupsList”: [
{
“paymentType”: “CASH”,
“paymentTypeId”: 1,
“internalPaymentTypeId”: 1
}
]
}
Response
{
“success”: true,
“data”: {
“id”: “b32b2d8e-bfd7-45e0-a17e-1260e8bdc12a”
},
“error”: null
}
2.2 Create draft check
Body
{
“shiftId”: “44f4056b-b19c-4550-a56d-2e4fd03a010c”,
“productsOutOfTheBoard”: [
{
“name”: “Яблука (перший гатунок)”,
“quantity”: 3,
“price”: 10.50,
“tx”: “1”,
“measurementId”: 2 // кг
},
{
“name”: “Рис”,
“quantity”: 2,
“price”: 34.90,
“tx”: “1”,
“measurementId”: 2 // кг
}
]
}
Response
{
“success”: true,
“data”: {
“id”: “7eae5195-d517-4dad-93ef-a751e2e6c593”
},
“error”: null
}

2.3 OpenShift
Body
{
“publicKey”: “…”,
“keyHash”: “…”,
“signTokenId”: “49f42fa8-4701-40e9-bd98-d7a0499295b1”
}
Response
{
“success”: true,
“data”: {
“id”: “44f4056b-b19c-4550-a56d-2e4fd03a010c”,
“workerId”: 1347,
“cashRegisterId”: “37032”,
“companyId”: “839”,
“startTime”: 1695556907,
“endTime”: null,
“status”: “OPEN”,
“cashRegisterName”: “Касса”,
“createdAt”: 1695556913132,
“updatedAt”: 1695556913132,
“device”: “device”,
“rawData”: {}
},
“error”: null
}

2.4 CloseShift
Body
{
“publicKey”: “…”,
“keyHash”: “…”,
“signTokenId”: “49f42fa8-4701-40e9-bd98-d7a0499295b1”,
“shiftId”: “1013ecd5-bb7b-49df-a5eb-3c656a95f775”
}
Response
{
“success”: true,
“data”: {
“id”: “1013ecd5-bb7b-49df-a5eb-3c656a95f775”,
“workerId”: 1347,
“cashRegisterId”: “37032”,
“companyId”: “839”,
“startTime”: 1695556613,
“endTime”: 1695556638790,
“status”: “CLOSE”,
“cashRegisterName”: “Касса”,
“createdAt”: 1695556619616,
“updatedAt”: 1695556619616,
“device”: “device”,
“rawData”: {}
},
“error”: null
}

Додаткова інформація
Roles
id
title
1
Власник
2
Адміністратор
3
Аналітик
4
Касир

Check types

SELLING
чек продажу
DRAFT
префіскалізований чек
OPEN_SHIFT
чек відкриття зміни
CLOSE_SHIFT
чек закриття зміни
OPNE_OFFLINE
чек відкриття офлайну
CLOSE_OFFLINE
чек закриття офлайну
CANCEL
відміна чека
RETURNING
відміна товару з чека
SERVICE
сервісні чеки

Payment group
id
title
type
1
Продаж
sale
2
Передплата
prepayment
3
Післяплата
postpaid

Internal Payment type
id
title
type
1
Готівка
cash
2
Сторонній POS термінал
anotherDevice
3
Картка (терм.) /NFC оплата (тел)
card
4
Передплата
subscription
5
Післяплата
postpaid
6
Еквайринг
acquiring
7
Платіжна система
paymentSystem
8
Нова пошта
novaposhta
9
Кредит
credit
10
Чек
check
11
Бонусні бали
bonusPoints
12
Кур’єрська доставка
expressDelivery
13
Бонуси
bonuses
14
Відстрочка платежу
deferredPayment
15
QR код
qrcode
16
Безготівкова оплата на рахунок
cashlessPaymentAccount
17
Поточний рахунок
currentBalance
18
Без доплати
noSurcharge
19
Доплата готівкою
surchargeInCash
20
Доплата POS-терміналом
surchargeInCard
21
Доплата QR-код
surchargeInQrcode
22
Зовнішня кур’єрська доставка
externalExpressDelivery
23
Перевізник
transporter

Measurements
id
title
integers
precision
1
шт
t
0
2
кг
f
3
3
л
f
3
4
послуга
t
0
5
м
f
3
6
пог.м
f
3
7
порція
t
1
8
грам
f
3
9
мл
f
3
10
кв.метр
f
3
11
пара
t
1
12
година
t
1
13
доба
t
1
14
місяць
t
1
15
тиждень
t
0
16
центнер
f
3
17
тонна
f
3
18
куб метр
f
3
19
автомоб день
t
1
20
автомоб год
t
1
21
тюбик
t
1
22
пачка
t
1
23
комплект
t
1

Помилки
Загальні

Messages

Company not found
Компанія користувача не знайдена
Cash register not found
Каса користувача не знайдена
Config does not provided
Конфігурації по компанії не знайдені
Key not found
Відсутній зареєстрований ключ
KEY_NOT_FOUND
Відсутній ключ для сесії сайфера. Необїідно викликати /v2/open-api/auth/get-sign-token

Зміна
Відкриття зміни
Shift is already opened
Зміна вже відкрита

Закриття зміни
Report is not found
Помилка при генерації z-звіту

Чеки
Створення префіскалізованого чеку
Tx-products is wrong for goods
Не вказаний параметр tx для товару

Фіскалізація чеку
Pre-check is absent in s3
Префіскалізованний чек не знайдено
Combine pay do not implements
Помилка при використанні одночасного типу оплати CASH і NON_CASH
Not validate payment
Не вказаний тип оплати
Shift not found
Зміна не знайдена
This shift not open
Зміна не відкрита

Відміна чеку
You cannot cancel a check posted at another cash register
Неможливо відмінити чек який був проведений на іншій касі
No enough cash
Недостатньо коштів у касі для відміни чеку
Raw data not found
Чек не знайдено
Shift not found
Зміна не знайдена
Check already cancelled
Чек вже відмінений

Часткова відміна чеку

Cashregister not found
Каса не знайдена
Shift not found
Зміна не знайдена
This shift not open
Зміне не відкрита
Not enough cash
Недостатньо коштів для часткової відміни

Авторизация
Отримання signTokenId

File is required
Необхідно передати файл для подальшого отримання ідентифікаторів сесії.
Missing caId argument