DeepLoyalty API без ПІІ

Цей API не обробляє персональні ідентифікаційні дані (ПІІ). Визначення ПІІ та ендпоінти Фази 2, які їх використовують, див. у API з PII (фаза 2).

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

Основне завдання: надіслати інформацію про чек, щоб додати його до транзакції за карткою.

Авторизація

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

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

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

Приклад:

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

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

Діаграма послідовності

Діаграма послідовності — API без ПІІ (Фаза 1)

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

Метод: PUT

URL: /v3/receiptNI

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

Параметр	Тип	Обов’язковий	Опис
`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 терміналу
`position`	object (array minimum 1 item)	Так	Опис нижче
`terminal_auth_code`	string	Так	Код терміналу
`card_id`	string	Ні	ID картки лояльності — мінімум 2 символи, якщо поле передано
`store_id`	string	Так	ID магазину
`cashier_id`	string	Так	ID касира
`cashback_amount`	number	Ні	Сума кешбеку

Масив `position`

Параметр	Тип	Обов’язковий	Опис
`pos_id`	string	Так	Номер позиції в чеку
`sku`	number	Так	Код товару
`prod_name`	string	Ні	Назва товару
`price`	number	Так	Ціна зі знижкою //якщо qty більше одного, вкажіть загальну суму ціни (див. приклад нижче)
`qty`	number	Так	Кількість
`type_qty`	string	Так	Тип одиниць виміру товару (штуки, літри тощо)
`classificator`	object (array minimum 1 item)	Так	Опис нижче
`ean13`	string	Ні	Штрихкод товару
`ccm`	string	Ні	Код країни виробника

Об’єкт `classificator`

Параметр	Тип	Обов’язковий	Опис
`name_level`	string	Так	Назва категорії товару
`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",
  "position": [
    {
      "pos_id": "1",
      "sku": 2588368,
      "ean13": "barcode",
      "ccm: "804",
      "prod_name": "Хліб",
      "price": 25,
      "qty": 1,
      "type_qty": "шт.",
      "classificator": [{"id": "285", "name_level": "Випічка"}] //if classificator has more than one category id, the main category is first
    },
    {
      "pos_id": "1",
      "sku": 243321,
      "ean13": "barcode",
      "ccm: "804",
      "prod_name": "Сир твердий",
      "price": 50, //one item cost 25, but we have 2 - 25*2 = 50
      "qty": 2,
      "type_qty": "шт.",
      "classificator": [{"id": "194", "name_level": "Молочні вироби"}]
    }
  ]
}

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

HTTP-код: 201

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

HTTP-код: 400

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

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

Коди помилок

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

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

Надіслати чек — діаграма послідовності

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

Метод: PUT

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

Заголовки:

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

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

Параметр	Тип	Обов’язковий	Опис	Add information
`bank_id`	uuid	Так	ID банку
`retailer_id`	uuid	Так	ID ритейлера
`order_id`	string	Так	ID чека
`date_time`	datetime	Так	Дата/час покупки. Формат yyyy-mm-dd HH:MM:SS	(ISO string for monobank - 2022-05-04T11:12:00.000Z)
`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`	object	Так	Посилання на відсканований фіскальний чек.”fiscal_url”:[] — без посилання, “fiscal_url”:[“https://…”] — одне посилання, “fiscal_url”:[“https://…,https://… ”] — два посилання
`terminal_id`	string	Так	ID терміналу
`position`	object	Так	Опис нижче
`trace_id`	uuid	Так	Унікальний ідентифікатор для співставлення транзакцій між ритейлером і банком
`terminal_auth_code`	string	Так	Код авторизації терміналу (код підтвердження)
`card_id`	string	Ні	ID картки лояльності. Може не надсилатися, якщо ритейлер не передав значення
`store_id`	string	Ні	ID магазину
`cashier_id`	string	Ні	ID касира
`is_review`	boolean	Так	Показувати користувачу опитування про роботу менеджера чи ні
`card_is_using`	boolean	Так	Ритейлер підключений до картки лояльності чи ні: true/false	для відображення кнопки відкриття картки лояльності або перегляду балансу картки
`cashback_amount`	number	Ні	Сума кешбеку

Масив `position`

Параметр	Тип	Обов’язковий	Опис
`pos_id`	number	Так	Номер позиції в чеку
`sku`	number	Так	Код товару
`prod_name`	string	Ні	Назва товару
`price`	number	Так	Ціна зі знижкою
`qty`	number	Так	Кількість
`type_qty`	string	Так	Тип одиниць виміру товару (штуки, літри тощо)
`classificator`	object (array minimum 1 item)	Так	Опис нижче
`ean13`	string	Ні	Штрихкод товару
`ccm`	string	Ні	Код країни виробника

Об’єкт `classificator`

Параметр	Тип	Обов’язковий	Опис
`name_level`	string	Ні	Назва категорії товару
`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",
  "position": [
    {
      "pos_id": 0,
      "sku": 2588368, //there can be 12 characters
      "ean13": "barcode",
      "ccm: "804",
      "prod_name": "Хліб",
      "price": 25,
      "qty": 1,
      "type_qty": "шт.",
      "classificator": [{"id": "285", "name_level": "Випічка"}] //if classificator has more than one category id, the main category is first
    },
    {
      "pos_id": 1,
      "sku": 243321,
      "ean13": "barcode",
      "ccm: "804",
      "prod_name": "Сир твердий",
      "price": 50, //one item cost 25, but we have 2 - 25*2 = 50
      "qty": 2,
      "type_qty": "шт.",
      "classificator": [{"id": "194", "name_level": "Молочні вироби"}]
    }
  ]
}

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

HTTP-код: 200

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

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

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

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

sum_after_discounted
terminal_auth_code
terminal_id
date_time

Метод: PATCH

URL: /receiptNI

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	Так	Унікальний ідентифікатор для співставлення транзакцій між ритейлером і банком. Той самий trace_id, який Deeployalty надсилає разом із чеком банку.

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

Статус	Опис
`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	Помилка збереження в чергу

Ритейлери та ID банку

Додаткову інформацію про retailer_id та bank_id можна знайти тут: Bank and Retailer ID.

DeepLoyalty API без ПІІ

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

Авторизація

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

Діаграма послідовності

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

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

Масив position

Об’єкт classificator

Body:

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

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

Коди помилок

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

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

Масив position

Об’єкт classificator

Body:

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

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

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

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

Body:

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

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

Коди помилок

Ритейлери та ID банку

Масив `position`

Об’єкт `classificator`

Масив `position`

Об’єкт `classificator`