DeepLoyalty API з PII

Що таке PII?

Персональні дані, також відомі як особиста інформація або персонально ідентифікована інформація (PII) (джерело)

У нашому випадку PII включає:

Ім’я клієнта
Телефон
Дату народження клієнта

Вимоги до Bank API

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

Загальна схема — отримання картки лояльності (банк, платформа, ритейлер)

Загальна схема — обробка чеків і нарахування бонусів

Основні дані передаються з платформи до ритейлера

Отримання токена авторизації для доступу до API ритейлера
Реєстрація\пошук клієнта (після отримання згоди від клієнта)
Ініціювання нарахування бонусів на основі чека та знайденого клієнта

Основні дані передаються від ритейлера до платформи

Отримання токена авторизації для доступу до API платформи
Загальна інформація про всі безготівкові покупки (як ідентифіковані з нарахованими бонусами, так і неідентифіковані) з метою:
- Ідентифіковані покупки — інформація про нараховані бонуси одразу передається до банківської виписки для відображення клієнту
- Неідентифіковані покупки — ідентифікуємо покупки шляхом порівняння з транзакціями клієнта на картках і подальшого додаткового нарахування бонусів клієнту на основі структури чека
1. Факт нарахування бонусів після успішного знаходження чека та транзакції клієнта

BASE_URL:

	dev	prod
	https://api.dev.deeployalty.io	https://api.deeployalty.io

Банки

Авторизація

Отримання списку ритейлерів

Метод: GET

URL: /retailers

Параметри: sortByName

Доступні значення: ASC, DESC

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

HTTP-код: 200

{
  "result": "ok",
  "traceID": "24f6550d-8fdd-4aaf-bc42-677cc588f2d8",
  "retailers": [
    {
      "retailerId": "0b92202e-5b79-480f-9b3e-33679b81372e",
      "name": "KIMS",
      "nameEn": "KIMS",
      "description": "KIMS - Мережа хімчисток одягу та взуття в Україні",
      "logoUrl": "https://loyalty-cads-deeployalty-static-file-storage.s3.eu-central-1.amazonaws.com/70b2ad1b-1093-441c-adf1-f6f724a640fb",
      "iosAppUrl": null,
      "androidAppUrl": null,
      "dateOfAdd": "2024-11-05",
      "codeType": "Code 39",
      "useCode": true
    },
    {
      "retailerId": "1e931bd9-9309-4474-babc-6196f4a16089",
      "name": "SOCAR Energy",
      "nameEn": "SOCAR Energy",
      "description": "Socar — мережа автозаправних комплексів в Україні",
      "logoUrl": "https://loyalty-cads-deeployalty-static-file-storage.s3.eu-central-1.amazonaws.com/0808d0b3-6c90-4ef4-8ab2-4d48a27c3759",
      "iosAppUrl": "https://apps.apple.com/ua/app/socarlevel/id691196059?l=uk",
      "androidAppUrl": "https://play.google.com/store/apps/details?id=com.bizico.socar&hl=uk",
      "dateOfAdd": "2024-11-05",
      "codeType": "pdf417",
      "useCode": true
    }
  ]
}

Опис об’єкта відповіді

Параметр	Тип	Опис
`result`	string	Статус відповіді ok/error
`retailers`	array	Масив ритейлерів

Опис масиву retailers

Параметр	Тип	Опис
`retailerId`	string	Статус відповіді ok/error
`name`	string	Назва ритейлера
`description`	string	Опис ритейлера
`logoUrl`	string	URL логотипу ритейлера
`iosAppUrl`	string	URL iOS-додатку ритейлера
`androidAppUrl`	string	URL Android-додатку ритейлера
`useCode`	boolean	Ритейлер використовує QR/BAR-коди
`dateOfAdd`	string	дата додавання до системи
`codeType`	string	тип qr\barcode

Відповідь з помилкою

HTTP-код: 500

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

{
  "result": "error",
  "error": {
    "...": "..."
  },
  "traceID": "e63b811e-aab1-4de5-be73-b2b1ed291b7f",
  "statusCode": 500
}

Отримання відкритих карток лояльності користувача за банком

Ендпоінт: /cards/customer

Метод: GET

Параметри: customerId

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

HTTP-код: 200

{
  "result": "ok",
  "traceID": "08a3e1cb-32dc-4af3-a6d6-f42a00a7b60f",
  "cards": [
    {
      "bankId": "5aec26a8-d2da-49a3-96be-b9da2448f426",
      "retailerId": "b7720467-363d-4c5a-aabd-b51cd595856d",
      "customerId": "29090",
      "cardNumber": "+11088775032",
      "statusCode": "d44e29c2-ba73-4f66-8186-e14f88c4dd6f",
      "createdAt": "2024-10-10T14:32:19.674Z"
    },
    {
      "bankId": "5aec26a8-d2da-49a3-96be-b9da2448f426",
      "retailerId": "09238c4a-cbe2-4a96-b15d-d678ec921691",
      "customerId": "29090",
      "cardNumber": "0e8ba4fd-3e85-11ef-a97a-005056b90a07",
      "statusCode": "d44e29c2-ba73-4f66-8186-e14f88c4dd6f",
      "createdAt": "2024-11-07T18:45:23.867Z"
    }
  ]
}

Відповідь

Опис об’єкта відповіді

Поле	Тип	Опис
`result`	string	Статус відповіді ok/error
`cards`	array	Масив ритейлерів

Опис масиву retailers

Поле	Тип	Опис
`bankId`	string	Унікальний ID банку
`retailerId`	string	Унікальний ID ритейлера
`customerId`	string	Унікальний ID клієнта в банку
`cardNumber`	string	Номер картки користувача
`statusCode`	string	Статус картки лояльності. d44e29c2-ba73-4f66-8186-e14f88c4dd6f — знайдено існуючу картку, e8b8b056-0291-45b8-9ff0-7eb0489ab837 — зареєстровано нову картку
`createdAt`	string	Дата створення картки лояльності

Пошук\реєстрація картки лояльності (банк)

Метод: POST

URL: /card

Картка лояльності — реєстрація / пошук (банк)

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

Параметр	Тип	Обов’язковий	Опис
`retailers`	array of uuid	Так	Масив ID ритейлерів
`first_name`	string	Так	Ім’я клієнта
`middle_name`	string	Так	По батькові клієнта
`last_name`	string	Так	Прізвище клієнта
`date_birth`	date	Так	Дата народження клієнта. Формат yyyy-mm-dd
`phone`	string	Так	Номер телефону клієнта (без ”+“)
`email`	string	Так	Email клієнта
`customerId`	string	Так	ID клієнта в банку

Тіло запиту:

{
  "retailers": ["09238c4a-cbe3-4a96-b15d-d678ec921692", "b4a12b27-21db-4c55-9b1e-00b914f3ffd8"],
  "first_name": "Іван",
  "middle_name": "Васильович",
  "last_name": "Петров",
  "date_birth": "1983-07-21",
  "phone": "380992222222",
  "email": "petrov.ivan@gmail.com",
  "customerId": "1234567890"
}

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

HTTP-код: 201

{
  "message": "Successfully received",
  "traceID": "b5a12b39-62dd-4e55-8b2e-01b914f3gfd5"
}

Асинхронна відповідь до Bank API

{
  "result": "ok",
  "card": "777777208698700",
  "balance": 0,//in uah
  "cardStatus": "e8b8b056-0291-45b8-9ff0-7eb0489ab837",
  "traceID": "e63b811e-aab1-4de5-be73-b2b1ed291b7f",
  "retailerId": "c4a12b27-21db-4c55-9b1e-00b914f3ffd8"
}

Опис об’єкта відповіді

Параметр	Тип	Опис
`result`	string	Статус відповіді ok/error
`card`	string	Номер картки лояльності
`cardStatus`	uuid	Статус картки: d44e29c2-ba73-4f66-8186-e14f88c4dd6f — знайдено існуючу картку; e8b8b056-0291-45b8-9ff0-7eb0489ab837 — зареєстровано нову картку
`balance`	number	Баланс картки лояльності
`traceID`	uuid	ID запиту
`retailerId`	uuid	ID ритейлера

Відповідь з помилкою

HTTP-код: 400

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

{
  "result": "error",
  "description": "Validation error",
  "error": "\"date_birth\" is required",
  "traceID": "87fdfae6-9340-4b23-a73b-233d0c35bf11"
}

Асинхронна відповідь з помилкою до Bank API

{
  "result": "error",
  "description": "Registration error",
  "error": "Client not found",
  "traceID": "87fdfae6-9340-4b23-a73b-233d0c35bf11",
  "retailerId": "c4a12b27-21db-4c55-9b1e-00b914f3ffd8",
  "statusCode": 404
}

Отримання балансу картки лояльності (банк)

Метод: POST

URL: /balance

Картка лояльності — отримання балансу (банк)

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

Параметр	Тип	Обов’язковий	Опис
`retailerId`	uuid	Так	ID ритейлера
`customerId`	string	Так	ID клієнта в банку

Тіло запиту:

{
  "retailerId": "09238c4a-cbe3-4a96-b15d-d678ec921692",
  "customerId": "1234567890"
}

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

HTTP-код: 200

{
  "result": "ok",
  "card": "777777208698700",
  "balance": 0,//in uah
  "traceID": "e63b811e-aab1-4de5-be73-b2b1ed291b7f",
  "retailerId": "c4a12b27-21db-4c55-9b1e-00b914f3ffd8"
}

Опис об’єкта відповіді

Параметр	Тип	Опис
`result`	string	Статус відповіді ok/error
`card`	string	Номер картки лояльності
`balance`	number	Баланс картки лояльності
`traceID`	uuid	ID запиту
`retailerId`	uuid	ID ритейлера

Відповідь з помилкою

HTTP-код: 400/500

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

{
  "result": "error",
  "error": {
    "...": "..."
  },
  "traceID": "e63b811e-aab1-4de5-be73-b2b1ed291b7f",
  "retailerId": "c4a12b27-21db-4c55-9b1e-00b914f3ffd8"
}

Помилки

Параметр	Тип	Опис
`error`	object	Помилка ритейлера

Отримання QR/Bar-коду картки лояльності (банк)

Метод: POST

URL: /qr

Картка лояльності — отримання QR / штрихкоду (банк)

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

Параметр	Тип	Обов’язковий	Опис
`retailerId`	uuid	Так	ID ритейлера
`customerId`	string	Так	ID клієнта в банку

Тіло запиту:

{
  "retailerId": "09238c4a-cbe3-4a96-b15d-d678ec921692",
  "customerId": "1234567890"
}

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

HTTP-код: 200

{
  "result": "ok",
  "type": "qr",
  "cardType": "bonus",
  "code": "AAKLSJWJJJJJDPWPFRFVHWJWHWWWWFSFFDDS...FDFFFHJDGKLDSHNDSLDSKGLFLSDJSDJHSHFLDFL9FDKEJHW",
  "codeExpire": "1718305539438",
  "traceID": "ace75bae-ee93-415f-8cb1-0642b1269ba2",
  "retailerId": "c4a12b27-21db-4c55-9b1e-00b914f3ffd8"
}

//value in timestamp (without timezone) or null - if qr is static

HTTP-код: 200

{
  "result": "ok",
  "type": "Code 128", for barcode
  "cardType": "discount",
  "code": "AAKLSJWJJJJJDPWPFRFVHWJWHWWWWFSFFDDS...FDFFFHJDGKLDSHNDSLDSKGLFLSDJSDJHSHFLDFL9FDKEJHW",
  "traceID": "ace75bae-ee93-415f-8cb1-0642b1269ba2",
  "retailerId": "c4a12b27-21db-4c55-9b1e-00b914f3ffd8"
}

Типи штрихкодів:

UPC-A
UPC-E
Code 128
EAN-13
EAN-8
Code 39
Interleaved 2 of 5
Codabar
pdf417

Опис об’єкта відповіді

Параметр	Тип	Опис
`result`	string	Статус відповіді ok/error
`type`	string	Тип коду (qr/bar)
`cardType`	string	bonus — ритейлер використовує картку лояльності з бонусами; discount — ритейлер використовує дисконтну картку без бонусів
`code`	string	Код картки лояльності
`traceID`	uuid	ID запиту
`retailerId`	uuid	ID ритейлера
`codeExpire`	string	час дії QR-коду

Відповідь з помилкою

HTTP-код: 400/500

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

{
  "result": "error",
  "error": {
    "...": "..."
  },
  "traceID": "e63b811e-aab1-4de5-be73-b2b1ed291b7f",
  "retailerId": "c4a12b27-21db-4c55-9b1e-00b914f3ffd8"
}

Помилки

Параметр	Тип	Опис
`error`	object	Помилка ритейлера

Інформація про нарахування бонусів (банк)

Метод: POST

URL: /transaction

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

Параметр	Тип	Обов’язковий	Опис
`transaction_id`	string	Так	ID транзакції в банку
`balance`	number	Так	Поточний бонусний баланс клієнта
`added_bonuses`	number	Так	Нараховані бонуси
`request_id`	string	Так	ID запиту банку

Тіло запиту:

{
  "transaction_id": "09238c4a-cbe3-4a96-b15d-d678ec921692",
  "request_id ": "33324995830-fd2324",
  "balance": 130,
  "added_bonuses": 23
}

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

HTTP-код: 200

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

{
  "transaction_id": "Transaction ID in bank",
  "status": "Status of adding bonuses"
}

Відповідь з помилкою

HTTP-код: 400

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

{
  "text": "Error text"
}

Скасування картки лояльності (банк)

Метод: POST

URL: /cancel

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

Параметр	Тип	Обов’язковий	Опис
`retailerId`	string	Так	ID ритейлера
`card`	number	Так	Поточний бонусний баланс клієнта
`customerId`	string	Так	ID клієнта

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

HTTP-код: 200

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

{
  "result": "ok",
  "card": "24087fee-2ccd-11ef-a97a-005056b90a07",
  "traceID": "357373d1-e24e-4105-bc70-805448728eab",
  "retailerId": "09238c4a-cbe2-4a96-b15d-d678ec921691"
}

Відповідь з помилкою

HTTP-код: 400

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

{
  "result": "error",
  "description": "Validation error",
  "error": {
    "message": "\"customerId\" is required"
  },
  "traceID": "e12791bb-ae5e-4667-9427-2713347105c5"
}

Список помилок Retailer API — Помилки Retailer API для картки лояльності

Ритейлери

Авторизація

Реєстрація/отримання номера картки лояльності

Метод: POST

URL: /card/register

Опис об’єкта заголовків

Параметр	Тип	Обов’язковий	Опис
`Authorization`	string	Так	Basic або інший тип заголовка авторизації

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

Параметр	Тип	Обов’язковий	Опис
`first_name`	string	Так	Ім’я клієнта
`middle_name`	string	Так	По батькові клієнта
`last_name`	string	Так	Прізвище клієнта
`date_birth`	date	Так	Дата народження клієнта у форматі “YYYY-MM-DD”
`phone`	string	Так	Номер телефону клієнта у форматі “380XXXXXXXXX”
`email`	string	Так	Email клієнта
`datetime`	number	Так	Поточний timestamp
`traceID`	uuid	Так	ID запиту

Тіло запиту:

{
  "first_name": "Ганна",
  "middle_name": "Петрівна",
  "last_name": "Шевченко",
  "date_birth": "1996-04-16",
  "phone": "380991234567",
  "email": "someemail.ganna@gmail.com",
  "datetime": 1693481166857,
  "traceID": "812191c4-612a-42d2-b45e-31055ee29c0a"
}

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

HTTP-код: 200

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

{
  "result": "ok",
  "card": "7777666655554444",
  "cardStatus": "e8b8b056-0291-45b8-9ff0-7eb0489ab837"
}

Опис об’єкта відповіді

Параметр	Тип	Обов’язковий	Опис
`result`	string	Так	Результат запиту (ok/error)
`card`	string	Так	Номер картки лояльності
`cardStatus`	uuid	Так	Статус картки: d44e29c2-ba73-4f66-8186-e14f88c4dd6f — знайдено існуючу картку; e8b8b056-0291-45b8-9ff0-7eb0489ab837 — зареєстровано нову картку

Відповідь з помилкою

HTTP-код: 400

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

{
  "result": "error",
  "error": "Error text or object"
}

Отримання балансу картки лояльності

Метод: GET

URL: /card/balance

Опис об’єкта заголовків

Параметр	Тип	Обов’язковий	Опис
`Authorization`	string	Так	Basic або інший тип заголовка авторизації

Параметри запиту

Параметр	Тип	Обов’язковий	Опис
`card`	string	Так	Номер картки лояльності клієнта

Приклад запиту: /card/balance?11122233444

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

HTTP-код: 200

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

{
  "result": "ok",
  "card": "7777666655554444",
  "balance": 123
}

//in uah

Відповідь з помилкою

HTTP-код: 400

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

{
  "result": "error",
  "error": "Error text or object"
}

Отримання QR/Bar-коду картки лояльності (банк)

Метод: GET

URL: /card/code

Опис об’єкта заголовків

Параметр	Тип	Обов’язковий	Опис
`Authorization`	string	Так	Basic або інший тип заголовка авторизації

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

Параметр	Тип	Обов’язковий	Опис
`card`	string	Так	Номер картки лояльності клієнта
`datetime`	number	Так	Поточний timestamp
`traceID`	uuid	Так	ID запиту

Тіло запиту:

{
  "card": "7777666655554444",
  "datetime": 1693481166857,
  "traceID": "812191c4-612a-42d2-b45e-31055ee29c0a"
}

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

HTTP-код: 200

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

{
  "result": "ok",
  "card": "7777666655554444",
  "type": "qr",
  "code": "AAKLSJWJJJJJDPWPFRFVHWJWHWWWWFSFFDDS...FDFFFHJDGKLDSHNDSLDSKGLFLSDJSDJHSHFLDFL9FDKEJHW"
}

// or “bar”

Відповідь з помилкою

HTTP-код: 400

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

{
  "result": "error",
  "error": "Error text or object"
}

Ідентифікація клієнта

Ідентифікація клієнта в ритейлера:

orderId - ID чека
customerId - ID клієнта

POST

URL: /customer_ident

Тіло запиту:

{
  "orderId": "Purchase receipt ID",
  "customerId": "customer's ID"
}

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

HTTP-код: 200

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

{
  "result": "ok"
}

Відповідь з помилкою

HTTP-код: 400

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

{
  "result": "error",
  "text": "error text"
}

Ініціювання нарахування бонусів

Після ідентифікації клієнта за чеком платформа надішле:

orderId - ID чека
transactionId - ID транзакції в банку (має бути повернутий у відповіді після зарахування бонусів)
card - Картка лояльності клієнта

POST

URL: /addbonuses

Тіло запиту:

{
  "orderId": "Purchase receipt ID",
  "transactionId": "Bank transaction ID",
  "card ": "Client's loyalty card number"
}

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

HTTP-код: 200

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

{
  "balance": "Client's current bonus balance",
  "added_bonuses": "Added bonuses"
}

//in uah

Відповідь з помилкою

HTTP-код: 400

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

{
  "text": "Error text"
}

Асинхронна відповідь для нарахування бонусів

Метод: POST

URL: /card/accrual

Опис об’єкта заголовків

Параметр	Тип	Обов’язковий	Опис
`Authorization`	string	Так	Basic або інший тип заголовка авторизації

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

Параметр	Тип	Обов’язковий	Опис
`card`	string	Так	Номер картки лояльності клієнта
`balance`	number	Так	Баланс картки лояльності клієнта
`added_bonuses`	number	Так	Нараховані бонуси
`order_id`	string	Так	ID замовлення чека

Тіло запиту:

{
  "card": "99087342111",
  "balance": 1496.87,
  "added_bonuses": 11.25,
  "order_id": "d44e29c2-ba73-4f66-8186-e14f88c4dd6f"
}

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

HTTP-код: 200

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

{
  "result": "ok"
}

Відповідь з помилкою

HTTP-код: 400

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

{
  "status": 400,
  "code": 1008,
  "message": "Error text"
}