DeepLoyalty API без ПІІ — короткий чек

Загальна схема

Загальна схема — Співставлення транзакцій

Авторизація

Усі запити до API використовують Bearer Token для авторизації.

Як згенерувати Bearer Token

Для генерації токена використовуйте JWT Authorization.

Приклад:

{
  "Authorization": "Bearer {{authToken}}"
}

Зверніть увагу: токен має термін дії.

Надіслати чек (Ритейлер)

Метод: PUT

URL: /v1/receiptNI/short

Опис об’єкта

Параметр	Тип	Обов’язковий	Опис
`retailer_id`	uuid	Так	ID ритейлера
`order_id`	string	Так	ID чека
`date_time`	datetime	Так	Дата/час покупки. Формат yyyy-mm-dd HH:MM:SS — місцевий час України
`rrn`	string	Так	Reference Retrieval Number
`pan_mask`	string	Так	Маскований номер картки
`added_bonuses`	number	Так	Нараховані бонуси на основі даних чеку в гривнях
`sum_before_discounted`	number	Так	Сума до знижки
`sum_after_discounted`	number	Так	Сума після знижки
`paid_by_bonus`	number	Так	Сплачені бонуси в гривнях
`fiscal_id`	string	Так	ID фіскального чека
`fiscal_url`	string	Так	Посилання на відсканований фіскальний чек. Як створити посилання — How to create fiscal url. Якщо в полі немає значення, надішліть два пробіли: `" "`
`terminal_id`	string	Так	ID терміналу
`terminal_auth_code`	string	Так	Код терміналу
`card_id`	string	Ні	ID картки лояльності — мінімум 2 символи, якщо поле передано
`store_id`	string	Так	ID магазину
`cashier_id`	string	Так	ID касира

Body:

{
  "retailer_id": "d516012c-a832-11ec-b909-0242ac120002",
  "order_id": "0224be24-a833-11ec-b909-0242ac120002",
  "date_time": "2022-03-20 18:20:03",
  "rrn": "232353634574657",
  "pan_mask": "446892..67",
  "added_bonuses": 5.34,
  "sum_before_discounted": 863.56,
  "sum_after_discounted": 853.56,
  "paid_by_bonus": 10.90,
  "terminal_id": "AF12312",
  "terminal_auth_code": "123",
  "fiscal_id": "333335",
  "fiscal_url": "https://cabinet.tax.gov.ua/cashregs/check?id=3000895246&fn=236070&date=2022-11-25",
  "card_id": "0123456789",
  "store_id": "127",
  "cashier_id": "099"
}

Успішна відповідь

HTTP-код: 201

Помилка відповіді

HTTP-код: 400

Тіло відповіді:

{
  "status": 400,
  "code": 1001,
  "message": "Save to queue error"
}

Коди помилок

Параметр	Тип	Опис
1000	number	Помилка валідації
1001	number	Помилка збереження в чергу

Webhook з чеком (Банк)

Цей об’єкт надсилається банку платформою DeepLoyalty після повної обробки чеку.

Метод: PUT

Ендпоінт: /api/receipt/deepLoyalty/short-order

Заголовки:

X-Token — токен автентифікації

Опис основного об’єкта

Параметр	Тип	Обов’язковий	Опис
`retailer_id`	uuid	Так	ID ритейлера
`order_id`	string	Так	ID чека
`date_time`	datetime	Так	Дата/час покупки. Формат yyyy-mm-dd HH:MM:SS — місцевий час України
`rrn`	string	Так	Reference Retrieval Number
`pan_mask`	string	Так	Маскований номер картки
`added_bonuses`	number	Так	Нараховані бонуси на основі даних чеку в гривнях
`sum_before_discounted`	number	Так	Сума до знижки
`sum_after_discounted`	number	Так	Сума після знижки
`paid_by_bonus`	number	Так	Сплачені бонуси в гривнях
`fiscal_id`	string	Так	ID фіскального чека
`fiscal_url`	string	Так	Посилання на відсканований фіскальний чек. Як створити посилання — How to create fiscal url. Якщо в полі немає значення, надішліть два пробіли: `" "`
`terminal_id`	string	Так	ID терміналу
`terminal_auth_code`	string	Так	Код терміналу
`card_id`	string	Ні	ID картки лояльності — мінімум 2 символи, якщо поле передано
`store_id`	string	Так	ID магазину
`cashier_id`	string	Так	ID касира
`is_review`	boolean	Так	Показувати користувачу опитування про роботу менеджера чи ні
`cardIssuing`	boolean	Ні	Чи підключений ритейлер до карток лояльності чи ні
`trace_id`	uuid	Так	Унікальний ідентифікатор для співставлення транзакцій між ритейлером і банком

Body:

{
  "bank_id": "d516012c-a832-11ec-b909-0242ac120002",
  "retailer_id": "c4a12b27-21db-4c55-9b1e-00b914f3ffd8",
  "order_id": "0224be24-a833-11ec-b909-0242ac120002",
  "date_time": "2022-03-20 18:20:03",
  "rrn": "232353634574657",
  "pan_mask": "446892..67",
  "added_bonuses": 5.34,
  "sum_before_discounted": 863.56,
  "sum_after_discounted": 853.56,
  "fiscal_id": "243842857245235",
  "fiscal_url": "https://...",
  or an array with two links for refills:
  "fiscal_url": ["https://cabinet.tax.gov.ua/cashregs/check?id=1138464&fn=3000514999&date=2024-06-12&time=07:21&sm=81.00",
  "https://cabinet.tax.gov.ua/cashregs/check?id=1138465&fn=3000514999&date=2024-06-12&time=07:21&sm=1249.72"],
  "paid_by_bonus": 10,
  "terminal_id": "AF12312",
  "terminal_auth_code": "qwe123",
  "card_id": "10093423334",
  "store_id": "1001",
  "is_review": true,
  "cardIssuing": false,
  "trace_id": "0224be24-a833-11ec-b909-0242ac120002"
}

Успішна відповідь

HTTP-код: 200

Тіло відповіді:

{
  "request_id": "64faf2b8-7840-4ff4-898b-3870c7c41762"
}

Оновити чек (Банк)

Банк знаходить і співставляє транзакцію за 4 параметрами:

sum_after_discounted
terminal_auth_code
terminal_id
date_time

Метод: PATCH

URL: /receiptNI/short

HEADERS:

Authorization Bearer {{authToken}}

Content-Type application/json

Опис об’єкта

Параметр	Тип	Обов’язковий	Опис
`request_id`	string	Так	ID чека, повернутий банком під час збереження чека
`bank_id`	uuid	Так	ID банку
`transaction_id`	string	Так	ID транзакції банку (якщо транзакцію знайдено); якщо транзакцію не знайдено, це поле не обов’язкове
`status`	uuid	Так	Статус транзакції
`customer_id`	string	Так	ID клієнта (якщо транзакцію знайдено); якщо транзакцію не знайдено, це поле не обов’язкове
`trace_id`	uuid	Так	Унікальний ідентифікатор для співставлення транзакцій між ритейлером і банком

Значення статусів

Статус	Опис
`d0bd04ba-62d0-4161-a31d-d82be5349591`	Знайдено
`20cb9c82-074e-4ace-bc41-9a9bedc736cd`	Не знайдено
`5130bf10-9560-4997-a672-ee8cf8a51c2e`	Банк витратив час на пошук

Body:

{
  "request_id": "64faf2b8-7840-4ff4-898b-3870c7c41762",
  "bank_id": "d516012c-a832-11ec-b909-0242ac120002",
  "transaction_id": "39d1ab13-10e4-4549-9885-1c6250641aab",
  "trace_id": "43f1ab67-10t6-6543-1234-1c545433aab"
  "status":
  "customer_id":
}

Успішна відповідь

HTTP-код: 201

Помилка відповіді

HTTP-код: 400

Тіло відповіді:

{
  "status": 400,
  "code": 1001,
  "message": "Save to queue error"
}

Коди помилок

Параметр	Тип	Опис
1000	number	Помилка валідації
1001	number	Помилка збереження в чергу