API відправки push-нотифікацій у мобільний додаток "Дія"

Платформа "Дія" надає авторизованим партнерам окремий REST API для відправки push-нотифікацій користувачам у мобільний застосунок. Наразі підтримуються наступні сценарії:

  • Створення шаблону push-нотифікації

  • Реєстрація розсилки push-нотифікацій на базі шаблону

  • Перевірка статусу розсилки push-нотифікацій

  • Отримання результату розсилки push-нотифікацій

  • Зупинка розсилки замовленої push-нотифікації

Для використання даних можливостей, необхідно:

  • Зареєструватись у якості авторизованого партнера та отримати Partner Token

  • Отримати дозвіл для авторизованого партнера на використання методів "Сервісу розсилки push-нотифікацій"

1. Взаємодія з сервісом розсилки push-нотифікацій "Дія"

diia-push-notification-flow

2. Аутентифікація авторизованого партнера

Сценарій доступний лише для авторизованого партнера за наявності Partner Token.

GET /api/v1/auth/partner/{partnerToken}

Таблиця 1. Параметри запиту
Параметр Тип Частина запиту Опис

partnerToken

string

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

Токен авторизованого партнера
Таблиця 2. Структура відповіді на запит
Json Path Тип Опис

$.token

string

Bearer-токен доступу для авторизованого партнера. Час життя токену - 2 години
Приклад відповіді
{
  "token": "<authorization token>"
}

3. Створення шаблону нотифікації

Отримання доступу до API можливе лише за умови проходження попередньої аутентифікації партнера та отримання Bearer-токену для подальшого використання при формуванні запитів.

POST /api/v1/notification/template

Параметр Тип Частина запиту Опційність Опис

Authorization

string

Заголовок

mandatory

Bearer-токен для проходження авторизації: "Bearer <bearer-token>"

$.actionType

string

Тіло запиту

mandatory

Тип спеціальної дії, котра має біти ініційована у застосунку по факту натискання з боку користувача на push-сповіщення або на повідомлення у відповідній вкладці застосунку. Для нотифікації стосовно відкриття нового кредиту на користувача, пропонуються до використання тип спеціальної дії newCredOpen

$.templateType

string

Тіло запиту

mandatory

Тип шаблону повідомлення. Обирається з довідника. В залежності від визначеного типу, повідомлення за створюваним шаблоном нотифікації буде відображено у застосунку із тип чи іншим ключовим заголовком. Для нотифікації стосовно відкриття нового кредиту на користувача, пропонуються до використання тип повідомлення attention ( Зверніть увагу)

$.timeToLiveInSec

number

Тіло запиту

optional

Час життя нотифікації. За замовчуванням, визначається рівним 14 діб.

$.removePrevious

boolean

Тіло запиту

optional

Ознака, що вказує на потребу видалення попередньої нотифікації, що була доправлена користувачеві за даним шаблоном із визначеним ідентифікатором ресурсу (екземпляру). За замовчуванням, визначається рівним true

$.needAuth

boolean

Тіло запиту

optional

Ознака, що вказує на потребу авторизації користувача для прочитання змісту повідомлення, котре буде доправлятися йому за даним шаблоном.

$.title

string

Тіло запиту

mandatory

Заголовок нотифікації. Відображається у якості заголовку push-сповіщення. Рекомендована довжина до 60 символів.

$.shortText

string

Тіло запиту

mandatory

Короткий текст. Відображається у якості тексту push-сповіщення та короткого змісту повідомлення у відповідній вкладці застосунку, та заголовку повного тексту повідомлення. Рекомендована довжина до 200 символів.

$.fullText

string

Тіло запиту

mandatory

Повний текст. Відображається у якості повного тексту повідомлення у відповідній вкладці застосунку. Рекомендована довжина 2048 символів.
Приклад тіла запиту
{
  "actionType": "message",
  "templateType": "attention",
  "title" : "Українське бюро кредитних історій",
  "shortText" : "Новий кредитний договір у кредитній історії",
  "fullText" : "У кредитну історію надійшла інформація про новий кредитний договір:\n\nдата відкриття - {dateCredOpen},\nкредитор - {creditor}.\n\n\n📥 Отримати кредитну історію можна на сайті Українського бюро кредитних історій - ubki.ua. \n\n⛔️ У разі виявлення шахрайських дій щодо вас або помилки кредитора - оскаржіть дані у кредитній історії."
}
Таблиця 3. Структура відповіді на запит
Json Path Тип Опис

$.templateId

string

Ідентифікатор створеного шаблона нотифікації
Приклад відповіді на запит
{
  "templateId": "6132008a2db328003c5d1d43"
}
Приклад відповіді у разі помилки
{
  "name": "Error",
  "message": "\"Create Template\" scope required",
  "code": 403,
  "data": {}
}
Таблиця 4. Коди відповідей
Код Опис

201

Шаблон створено успішно

403

Помилка авторизації запиту

4. Реєстрація розсилки push-нотифікацій за заданим шаблоном

Отримання доступу до API можливе лише за умови проходження попередньої аутентифікації партнера та отримання Bearer-токену для подальшого використання при формуванні запитів.

POST /api/v1/notification/distribution/push

Максимальна кількість отримувачів push-нотифікації = 10 000
Параметр Тип Частина запиту Опційність Опис

Authorization

string

Заголовок

mandatory

Bearer-токен для проходження авторизації: "Bearer <bearer-token>"

$.templateId

string

Тіло запиту

mandatory

Ідентифікатор шаблону, за котрим має бути виконано розсилку на визначених отримувачів. Отримується у відповідь на запит на створення шаблону розсилки, у разі успішної реєстрації шаблону.

$.recipients

array

Тіло запиту

mandatory

Масив отримувачів, на котрих має бути виконано розсилку у визначеному шаблоні. Максимальний розмір, що приймається системою - до 10 000 отримувачів за запит.

$.recipients[].rnokpp

string

Тіло запиту

mandatory

РНОКПП отримувача - ідентифікатор за котрим система визначить отримувача повідомлення.

$.recipients[].id

string

Тіло запиту

mandatory

Ідентифікатор користувача в 3rd-party системі партнера

$.recipients[].resourceId

string

Тіло запиту

optional

Ідентифікатор сутності, щодо котрої надсилається нотифікація для визначеного отримувача. Якщо даний параметр не визначено - при натисканні користувача на push-сповідення або відповідне повідомлення, йому буде відображено повідомлення з повним змістом fullText.

$.recipients[].parameters

array

Тіло запиту

optional

Масив об’єктів, що визначають значення параметрів, що можуть бути визначеними у шаблоні заданої нотифікації. Якщо параметр в шаблоні присутній, проте у запиті на реєстрацію розсилки його не визначено (такого ключа для користувача не задано) - статус розсилки по даному користувачеві буде встановлено, як notification-generation-error

$.recipients[].parameters[].key

string

Тіло запиту

mandatory

Назва параметра шаблону нотифкації. Використовується у тексті нотифікації {key}

$.recipients[].parameters[].value

string

Тіло запиту

mandatory

Значення параметра шаблону нотифікації, визначене для конкретного адресата.
Приклад тіла запиту
{
    "templateId": "string",
    "recipients": [
        {
            "rnokpp": "string",
            "id": "string",
            "resourceId?": "string",
            "parameters?": [
                {
                    "key": "string",
                    "value": "string"
                }
            ]
        }
    ]
}
Таблиця 5. Структура відповіді на запит
Json Path Тип Опис

$.distributionId

string

Ідентифікатор створеної розсилки нотифікацій
Приклад відповіді на запит
{
  "distributionId": "12345678901"
}

5. Отримання статусу розсилки push-нотифікацій

Отримання доступу до API можливе лише за умови проходження попередньої аутентифікації партнера та отримання Bearer-токену для подальшого використання при формуванні запитів.

GET /api/v1/notification/distribution/push/{distributionId}/status

Параметр Тип Частина запиту Опційність Опис

Authorization

string

Заголовок

mandatory

Bearer-токен для проходження авторизації: "Bearer <bearer-token>"

distributionId

string

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

mandatory

Ідентифікатор розсилки push-нотифікацій
Таблиця 6. Структура відповіді на запит
Json Path Тип Опис

$.status

string

Статус виконання розсилки push-нотифікацій:

['pending', 'in-progress', 'sent', 'closed']
Приклад відповіді на запит
{
  "status": "enum ['pending', 'in-progress', 'sent', 'closed']"
}

6. Отримання результату розсилки push-нотифікацій

Отримання доступу до API можливе лише за умови проходження попередньої аутентифікації партнера та отримання Bearer-токену для подальшого використання при формуванні запитів.

GET /api/v1/notification/distribution/push/{distributionId}

Параметр Тип Частина запиту Опційність Опис

Authorization

string

Заголовок

mandatory

Bearer-токен для проходження авторизації: "Bearer <bearer-token>"

distributionId

string

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

mandatory

Ідентифікатор розсилки push-нотифікацій
Таблиця 7. Структура відповіді на запит
Json Path Тип Опис

$.recipients

array

Перелік отримувачів розсилки

$.recipients[].id

string

Ідентифікатор користувача в 3rd-party системі партнера

$.recipients[].rnokpp

string

РНОКПП отримувача - ідентифікатор за котрим система визначить отримувача повідомлення.

$.recipients[].status

string

Статус виконання розсилки push-нотифікацій користувачу:

['pending', 'in-progress', 'sent', 'closed']
Приклад відповіді на запит
{
  "recipients": [
    {
      "id": "string",
      "rnokpp": "string",
      "status": "enum ['not-found', 'sent', 'read', 'error']"
    }
  ]
}

7. Зупинка розсилки push-нотифікацій

Отримання доступу до API можливе лише за умови проходження попередньої аутентифікації партнера та отримання Bearer-токену для подальшого використання при формуванні запитів.

DELETE /api/v1/notification/distribution/push/{distributionId}

Параметр Тип Частина запиту Опційність Опис

Authorization

string

Заголовок

mandatory

Bearer-токен для проходження авторизації: "Bearer <bearer-token>"

distributionId

string

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

mandatory

Ідентифікатор розсилки push-нотифікацій
Таблиця 8. Коди відповідей
Код Опис

204

Якщо розсилку не було запущено - її буде видалено без запуску. Якщо розсилка перебуває у процесі виконання - її буде зупинено.

8. Шаблонізація повідомлень у Дії

Відправка нотифікацій включає етап генерації фінального тексту нотифікації на базі створеного шаблона fullText та моделі даних із запиту, шляхом заміщення змінних вигляду {key} на відповідне значення поля моделі даних.

Приклад шаблону текстового повідомлення fullText
"У кредитну історію надійшла інформація про новий кредитний договір:\n
дата відкриття - {dateCredOpen},\nкредитор - {creditor}.\n
📥 Отримати кредитну історію можна на сайті Українського бюро кредитних історій - ubki.ua.\n
⛔️ У разі виявлення шахрайських дій щодо вас або помилки кредитора - оскаржіть дані у кредитній історії."
Приклад запиту на створення розсилки згідно шаблону та моделі даних для формування повідомлення
{
  "templateId": "<Ідентифікатор шаблона>",
  "recipients": [
    {
      "id": "<Ідентифікатор користувача у 3rd-party системі>",
      "rnokpp": "<ІПН користувача>",
      "parameters": [
        {
            "key": "dateCredOpen",
            "value": "01.08.2021"
        },
        {
            "key": "creditor",
            "value": "ПриватБанк"
        }
      ]
    }
  ]
}