API адмін-панелі кешбеку

ENV:

	Dev	Prod
	https://admin-panel.dev.deeployalty.io/deeployalty-admin/	https://admin-panel.deeployalty.io/deeployalty-admin/

Інструкція зі звірки кешбек-кампаній у порталі (звіти банку та мерчанта): звірка кешбек-кампаній.

Авторизація

Авторизація для всіх API відбувається за допомогою Bearer Token.

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

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

Приклад:

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

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

Отримання списку кешбеків

Метод: GET

Ендпоінт: /cashbacks/for-bank

Параметри: /cashbacks

Параметр	Тип	Обов’язковий	Опис
`name`	integer	Ні	Назва кешбеку
`sku`	array [“string”]	Ні	SKU товару
`retailerId`	string	Ні	ID мерчанта
`status`	string	Ні	Конкретний статус кешбеку
`bankApprovalStatus`	string	Ні	Група статусів кешбеку в банку (див. Статус банку нижче)
`dateTo`	string	Ні	Дата початку кешбеку
`dateFrom`	string	Ні	Дата завершення кешбеку

Статус кешбеку

Статус кешбеку	Опис
`active`	кешбек-кампанії розпочато і вони активні
`finished`	кешбек-кампанії завершено
`approved`	участь у кешбек-кампанії схвалено банком і мерчантом

Для інтеграції з адмін-панеллю та отримання всіх кешбек-кампаній, які дійсно схвалені банком і мерчантом і будуть активні на конкретну дату, потрібно брати статус active для всієї кампанії, а не лише active у масиві banks[].

Якщо кампанія активна і мерчант додає ще один термінал, повний список terminal id можна взяти в terminals[]. Наприклад, використовуйте сервіс, який раз на 12 годин перевіряє, чи змінилося це поле; якщо так — оновіть дані у своїй системі.

Статус банку

Статус банку	Опис
`pending`	кешбек-кампанія очікує рішення банку
`approved`	участь у кешбек-кампанії схвалено банком
`declined`	участь у кешбек-кампанії відхилено банком
`expired`	кешбек-кампанія завершилася або мерчант схвалив старт кампанії без цього банку

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

HTTP-код: 200

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

[
  {
    "cashbackId": "228536ee-7e97-451a-9296-ed79267fe3ce",
    "retailerId": "711df0c2-209c-4e54-accf-484820e7e43f",
    "banks": [
      {
        "id": "093e6c55-638d-4982-ba41-f0f769041a33",
        "status": "pending",
        "settlementConfirmed": false
      }
    ],
    "name": "testlili1709",
    "description": "11",
    "participationTerms": "fff",
    "bannerSmall": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBzdGFuZGFsb25lPSJubyI/Pgo8IURPQ1RZUEUgc3ZnIFBVQkx...",
    "bannerBig": "",
    "sku": [],
    "categoryId": ["10", "20", "30"],
    "dateFrom": "2025-11-30T21:00:00.000Z",
    "dateTo": "2026-01-31T20:59:59.999Z",
    "minAmount": 123,
    "maxAmount": 133,
    "maxBudget": 11111,
    "percentage": 10,
    "expectedCompensation": null,
    "countryId": "a7a3362b-7560-4398-8255-6d332411ab68",
    "terminals": [
      {
        "terminal_id": "t125128",
        "terminal_name": "Main Store Terminal",
        "terminal_location": "Kyiv, Main Street 1"
      },
      {
        "terminal_id": "123",
        "terminal_name": null,
        "terminal_location": null
      }
    ],
    "terminalsDeeployalty": false,
    "paymentSystemsId": [
      "8f2485fc-1bd8-4127-8765-06b81a02ed3d",
      "de63a5d2-d67e-4c0a-a747-75f4e1212c94",
      "e9c37e42-bcd5-4120-96f0-a39d3afb5b9e",
      "271dd644-c342-4e36-afb8-25c1652917da"
    ],
    "paymentSplit": "merchant",
    "merchantCommission": null,
    "status": "awaitingBankApproval",
    "createdAt": "2025-09-17T07:16:16.768Z",
    "updatedAt": "2025-09-17T07:16:16.768Z",
    "retailer": {
      "retailerId": "711df0c2-209c-4e54-accf-484820e7e43f",
      "name": "Deeployalty"
    },
    "country": {
      "id": "a7a3362b-7560-4398-8255-6d332411ab68",
      "name": "Ukraine",
      "code": "UA",
      "currency": {
        "code": "UAH",
        "icon": "",
        "name": "Ukrainian hryvnia",
        "symbol": "₴"
      }
    }
  }
]

Поле	Тип	Опис
`terminals`	array of objects	Список терміналів, пов’язаних із кешбеком
`terminals[].terminal_id`	string	Ідентифікатор терміналу
`terminals[].terminal_name`	string \| null	Назва терміналу (null, якщо недоступна)
`terminals[].terminal_location`	string \| null	Розташування терміналу (null, якщо недоступне)

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

HTTP-код: 400

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

{
  "statusCode": 400,
  "message": [
    "retailerId must be a UUID",
    "name must be shorter than or equal to 27 characters",
    "merchantCompensationPercentage must be at least 0"
  ],
  "error": "Bad Request"
}

Коди помилок:

400 — помилки валідації (невірний UUID, довжина рядка, діапазон числа)
401 — неавторизовано (відсутній або невірний JWT-токен)
403 — заборонено (недостатньо прав — потрібна роль ADMIN або EDITOR)

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

Метод: GET

Ендпоінт: deeployalty-admin/retailers

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

HTTP-код: 200

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

[
  {
    "retailerId": "711df0c2-209c-4e54-accf-484820e7e43f",
    "name": "Deeployalty",
    "webhookUrl": null,
    "apiUrl": null,
    "description": null,
    "logoUrl": "data:image/svg+xml;base64,PD94bWwg...",
    "iosAppUrl": null,
    "androidAppUrl": null,
    "login": null,
    "urlIdent": null,
    "rro": null,
    "nameEn": null,
    "cardIssuing": null,
    "cardPresentationId": "d29ea407-8f47-4b44-9826-f1db2e57fa75",
    "isReview": false,
    "isMask": false,
    "dataSaleToWebhook": null,
    "domain": ["deeployalty.io"],
    "excludedBank": null,
    "merchantCategoryCode": [
      "1111",
      "2222",
      "3333",
      "4444",
      "5555",
      "6666",
      "7777",
      "8888",
      "9999"
    ],
    "createdAt": "2025-07-24T14:18:29.944Z",
    "updateAt": "2025-10-24T11:28:13.695Z"
  }
]

Отримання даних мерчанта

Метод: GET

Ендпоінт: deeployalty-admin/retailers/

name

nameEn

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

HTTP-код: 200

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

{
  "retailerId": "711df0c2-209c-4e54-accf-484820e7e43f",
  "name": "Deeployalty",
  "webhookUrl": null,
  "apiUrl": null,
  "description": null,
  "logoUrl": "data:image/svg+xml;base64,PD94bWwg...",
  "iosAppUrl": null,
  "androidAppUrl": null,
  "login": null,
  "urlIdent": null,
  "rro": null,
  "nameEn": null,
  "cardIssuing": null,
  "cardPresentationId": "d29ea407-8f47-4b44-9826-f1db2e57fa75",
  "isReview": false,
  "isMask": false,
  "dataSaleToWebhook": null,
  "domain": ["deeployalty.io"],
  "excludedBank": null,
  "merchantCategoryCode": [
    "1111",
    "2222",
    "3333",
    "4444",
    "5555",
    "6666",
    "7777",
    "8888",
    "9999"
  ],
  "createdAt": "2025-07-24T14:18:29.944Z",
  "updateAt": "2025-10-24T11:28:13.695Z"
}

Підтвердження кешбек-кампанії банком

Метод: POST

Ендпоінт: /cashbacks?cashbackId/confirm

Параметри:

Параметр	Тип	Обов’язковий	Опис
`cashbackId`	uuid	Так	ID кешбеку

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

HTTP-код: 201

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "awaitingBankApproval",
  "message": "Cashback confirmed successfully",
  "createdAt": "2024-06-16T12:00:00Z",
  "updatedAt": "2024-06-16T12:00:00Z"
}

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

HTTP-код: 400

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

{
  "statusCode": 400,
  "message": "Cashback not found",
  "error": "Bad Request"
}

Коди помилок:

400 — Bad Request (кешбек не знайдено, невірний ID кешбеку)
401 — неавторизовано (відсутній або невірний JWT-токен)
403 — заборонено (недостатньо прав — потрібна роль ADMIN або EDITOR, або користувач не є банком)

Відхилення кешбек-кампанії банком

Метод: POST

Ендпоінт: /cashbacks?cashbackId/reject

Параметри:

Параметр	Тип	Обов’язковий	Опис
`cashbackId`	uuid	Так	ID кешбеку

Тіло запиту:

Параметр	Тип	Обов’язковий	Опис
`comment`	string	Ні	Коментар із причиною відхилення

{
  "comment": "Campaign does not meet our requirements"
}

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

HTTP-код: 201

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "awaitingBankApproval",
  "message": "Cashback confirmed successfully",
  "createdAt": "2024-06-16T12:00:00Z",
  "updatedAt": "2024-06-16T12:00:00Z"
}

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

HTTP-код: 400

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

{
  "statusCode": 400,
  "message": "Cashback not found",
  "error": "Bad Request"
}

Коди помилок:

400 — Bad Request (кешбек не знайдено, невірний ID кешбеку)
401 — неавторизовано (відсутній або невірний JWT-токен)
403 — заборонено (недостатньо прав — потрібна роль ADMIN або EDITOR, або користувач не є банком)