API адмін-панелі кешбеку для мерчантів

Зовнішнє API для інтеграції кор-проєкту мерчанта з адмін-панеллю кешбеків Deeployalty. Аналог API адмін-панелі кешбеку для банків, але для мерчантів (retailers).

Якщо ви раніше керували кешбек-кампаніями через портал Deeployalty, це API дозволяє виконувати ті самі дії програмно — без UI порталу.

ENV:

Swagger (OpenAPI)

Інтерактивна документація зі схемами запитів і відповідей:

У Swagger шукайте ендпоінти з префіксом /cashbacks/for-merchant.

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

Авторизація

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

Як отримати Bearer Token

Токен видається зовнішнім сервісом кор-проєкту:

Детальніше: JWT авторизація.

Мерчант отримує clientId та secret (креденшали кор-проєкту) так само, як банк. Отриманий JWT передається як Authorization: Bearer <token>.

Приклад:

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

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

Ролі (admin-panel JWT)

Якщо використовується JWT адмін-панелі (POST /auth/login з typeAccount=retailer):

• GET — доступні всім ролям мерчанта, включно з viewer
• POST / PATCH / DELETE / confirm — лише admin_user або editor, або Kong JWT (userType=kong_user)

Отримання списку підключених банків

Метод: GET

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

Повертає список банків, підключених до платформи, яких мерчант може запросити до участі в кешбек-кампанії. Банки з excludedBank мерчанта у відповіді не показуються.

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

HTTP-код: 200

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

[
  {
    "id": "093e6c55-638d-4982-ba41-f0f769041a33",
    "name": "TestbankLili",
    "logoUrl": "data:image/svg+xml;base64",
    "apiVersion": "1.0"
  }
]

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

• 401 — неавторизовано (відсутній або невірний токен)
• 403 — заборонено (токен належить банку, а не мерчанту)

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

Метод: GET

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

Список завжди фільтрується по мерчанту з токена. Параметри retailerId, bankId, createdByType недоступні — сервер підставляє їх автоматично.

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

HTTP-код: 200

{
  "data": [
    {
      "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",
      "status": "awaitingBankApproval",
      "dateFrom": "2025-11-30T21:00:00.000Z",
      "dateTo": "2026-01-31T20:59:59.999Z",
      "percentage": 10,
      "createdAt": "2025-09-17T07:16:16.768Z",
      "updatedAt": "2025-09-17T07:16:16.768Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 1,
    "totalItems": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}

Отримання кешбек-кампанії за ID

Метод: GET

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

Формат відповіді — як у внутрішнього GET /cashbacks/:cashbackId (деталі кампанії, банки, permissions, статистика).

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

• 403 — кампанія належить іншому мерчанту

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

Метод: POST

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

Поля creatorId і createdByType не приймаються в тілі запиту — сервер завжди виставляє їх з токена (creatorId = <retailerId>, createdByType = 'retailer').

Тіло запиту

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

HTTP-код: 201

{
  "id": "228536ee-7e97-451a-9296-ed79267fe3ce",
  "status": "awaitingBankApproval",
  "message": "Cashback successfully created",
  "createdAt": "2024-06-16T12:00:00Z",
  "updatedAt": "2024-06-16T12:00:00Z"
}

Редагування кешбек-кампанії

Метод: PATCH

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

Тіло запиту — як у внутрішнього PATCH /cashbacks/:cashbackId (UpdateCashbackDto, часткове оновлення). Поля creatorId, createdByType і retailerId не приймаються — сервер ігнорує їх. Діють ті самі бізнес-обмеження за статусом (permissions.editAbility), що й у внутрішньому API.

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

• 403 — кампанія належить іншому мерчанту

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

Метод: DELETE

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

М’яке видалення (статус → deleted). Дозволено лише автору кампанії, і лише якщо до старту кампанії залишилось не менше 2 днів.

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

• 403 — кампанія належить іншому мерчанту

Підтвердження запуску кампанії мерчантом

Метод: POST

Ендпоінт: /cashbacks/for-merchant/:cashbackId/confirm

Мерчант підтверджує запуск власної кампанії. Дозволено з двох статусів:

• awaitingMerchantApproval — штатний фінальний крок, коли всі запрошені банки вже прийняли рішення
• awaitingBankApproval — «передчасне підтвердження»: мерчант запускає кампанію раніше, щойно хоча б один банк погодився. Усі банки зі статусом pending автоматично переводяться в expired

В обох випадках потрібен хоча б один банк зі статусом approved, інакше — 400 Bad Request.

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

HTTP-код: 200 / 201

{
  "id": "228536ee-7e97-451a-9296-ed79267fe3ce",
  "status": "approved",
  "message": "Campaign launch confirmed successfully by merchant",
  "createdAt": "2024-06-16T12:00:00Z",
  "updatedAt": "2024-06-16T12:00:00Z"
}

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

HTTP-код: 400

{
  "statusCode": 400,
  "message": "Cannot confirm campaign: at least one bank must approve participation first",
  "error": "Bad Request"
}

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

• 400 — Bad Request (кампанію не знайдено, невірний статус, ще немає схваленого банку)
• 401 — неавторизовано (відсутній або невірний токен)
• 403 — заборонено (токен належить банку, або кампанія належить іншому мерчанту)