2FA API

BSG 2FA API — це RESTful API для двофакторної автентифікації користувачів на сайті чи у вебзастосунку: з його допомогою можна підтверджувати транзакції та контактні дані користувача, використовувати його як другий фактор автентифікації тощо.

BSG 2FA API дає змогу обрати канал надсилання одноразового пароля (OTP) користувачеві: SMS або Viber. Підключіть потрібний канал в особистому кабінеті на сторінці «Налаштування» розділу «2FA» — і починайте працювати з BSG 2FA API.

Зверніть увагу: 2FA API недоступний у демо-режимах акаунта (режимах, у яких дані вашого акаунта не верифіковано).

Переконайтеся, що ви вказали всі необхідні дані в налаштуваннях акаунта, щоб користуватися сервісом 2FA.

Доступні методи HTTP

1. Надіслати одноразовий пароль;
2. Повторно надіслати одноразовий код;
3. Перевірити одноразовий код;
4. Скасувати сесію автентифікації;
5. Перевірити статус автентифікації;
6. Отримати список сесій автентифікації.
7. Створити шаблон повідомлення;
8. Видалити шаблон повідомлення;
9. Отримати список шаблонів.

Надіслати одноразовий пароль

Цей виклик API використовується, щоб згенерувати й надіслати користувачеві одноразовий пароль у повідомленні SMS або Viber. Зверніть увагу: автентифікація отримувачів, які перебувають у стоп-листі SMS або Viber у вашій контактній книзі, відповідним методом неможлива. (Тобто якщо отримувач у стоп-листі SMS, то під час запиту автентифікації методом SMS одноразовий пароль не буде надіслано, а у відповідь ви отримаєте помилку).

Щоб надіслати одноразовий пароль, зробіть запит на цей URL:

Будьте надійними. Використовуйте 2FA
Почати

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

Приклад запиту

{ 

  "recipient": "61401629754", 
  "channel": "string", 
  "sender": "SENDER", 
  "sender_alt": "SENDER_ALT", 
  "template_id": "12", 
  "code_lifetime": 300, 
  "code_max_tries": 3, 
  "code_digits": 5 

}

Параметри відповіді

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

Відповідь у разі успішного запиту:

{
  "data": {
    "id": "bf4381c8-9d4a-4705-bd28-f89a830b7f96",
    "recipient": "380979965073",
    "status": "pending",
    "channel": "sms",
    "sender": "SENDER",
    "sender_alt": "SENDER_ALT",
    "message_text": "Your verification code: {code}",
    "code_lifetime": 300,
    "code_max_tries": 3,
    "code_digits": 5,
    "price": "0,02",
    "currency": "USD",
    "country_code": "UA",
    "expired_at": "2023-01-04 18:37:06",
    "created_at": "2023-01-04 17:37:06"
    "finished_at": "2023-01-04 17:37:06"
  }
}

Коди помилок

Повторно надіслати одноразовий код

Використовується для повторного надсилання одноразового пароля отримувачеві: генерується й надсилається в повідомленні новий одноразовий пароль, а попередній стає недійсним. Під час повторного надсилання для генерування OTP використовуються вже збережені дані із запиту https://one-api.bsg.world/api/2fa/authentications/otp

Цей виклик API доступний, лише якщо поточну автентифікацію не завершено до закінчення терміну її дії (термін дії автентифікації вказується в кожній відповіді 2FA API).

Щоб повторно надіслати одноразовий код, зробіть запит на цей URL:

Будьте надійними. Використовуйте 2FA
Почати

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

Параметри відповіді

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

Відповідь у разі успішного запиту:

{
  "data": {
    "id": "bf4381c8-9d4a-4705-bd28-f89a830b7f96",
    "recipient": "380979965073",
    "status": "pending",
    "channel": "sms",
    "sender": "SENDER",
    "sender_alt": "SENDER_ALT",
    "message_text": "Your verification code: {code}",
    "code_lifetime": 300,
    "code_max_tries": 3,
    "code_digits": 5,
    "price": "0,02",
    "currency": "USD",
    "country_code": "UA",
    "expired_at": "2023-01-04 18:37:06",
    "created_at": "2023-01-04 17:37:06"
    "finished_at": "2023-01-04 17:37:06"
  }
}

Коди помилок

Перевірити одноразовий код

Цей виклик API використовується, щоб перевірити, що одноразовий пароль, отриманий вами від користувача, збігається з надісланим BSG.

Щоб перевірити одноразовий код, зробіть запит на цей URL:

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

Параметри відповіді

Приклад відповіді, якщо код неправильний:

{
  "errors": [
    {
      "message": "The code does not match the expected value"
    }
  ]
}

Якщо одноразовий код правильний:

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

{
  "data": {
    "id": "bf4381c8-9d4a-4705-bd28-f89a830b7f96",
    "recipient": "380979965073",
    "status": "pending",
    "channel": "sms",
    "sender": "SENDER",
    "sender_alt": "SENDER_ALT",
    "message_text": "Your verification code: {code}",
    "code_lifetime": 300,
    "code_max_tries": 3,
    "code_digits": 5,
    "price": "0,02",
    "currency": "USD",
    "country_code": "UA",
    "expired_at": "2023-01-04 18:37:06",
    "created_at": "2023-01-04 17:37:06"
    "finished_at": "2023-01-04 17:37:06"
  }
}

Коди помилок

Скасувати сесію автентифікації

Використовується для скасування процесу автентифікації. У цьому разі автентифікація має бути в статусі Pending.

Щоб скасувати сесію автентифікації, зробіть запит на цей URL:

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

Параметри відповіді

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

Відповідь у разі успішного запиту:

{
  "data": {
    "id": "bf4381c8-9d4a-4705-bd28-f89a830b7f96",
    "recipient": "380979965073",
    "status": "canceled",
    "channel": "sms",
    "sender": "SENDER",
    "sender_alt": "SENDER_ALT",
    "message_text": "Your verification code: {code}",
    "code_lifetime": 300,
    "code_max_tries": 3,
    "code_digits": 5,
    "price": "0,02",
    "currency": "USD",
    "country_code": "UA",
    "expired_at": "2023-01-04 18:37:06",
    "created_at": "2023-01-04 17:37:06"
    "finished_at": "2023-01-04 17:37:06"
  }
}

Можливі помилки

Перевірити статус автентифікації

Використовується для отримання інформації про поточний статус автентифікації за її ідентифікатором.

Щоб перевірити статус автентифікації, зробіть запит на цей URL:

Будьте надійними. Використовуйте 2FA
Почати

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

Параметри відповіді

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

Відповідь у разі успішного запиту:

{

  "data": {

      "id": "ea5db413-e368-4952-b745-cc2030210c49", 
      "recipient": "380501403813", 
      "status": "verified", 
      "channel": "sms", 
      "sender": "testsms", 
      "sender_alt": "string", 
      "message_text": "Your BSG 2FA confirmation code is {code}. Do not share this with anyone else.", 
      "code_lifetime": 30, 
      "code_max_tries": 5, 
      "code_digits": 6, 
      "price": 50.25, 
      "currency": "EUR", 
      "country_code": "FR", 
      "expired_at": "2022-04-28 14:21:16", 
      "created_at": "2022-04-28 14:21:16", 
      "updated_at": "2022-04-28 14:21:16", 
      "finished_at": "2022-04-28 14:21:16", 

      "messages": [

        { 
          "id": "1ed32701-5d4f-6cfa-ba06-9db3aa8bab68", 
          "recipient": "61401629754", 
          "status": "accepted", 
          "channel": "sms", 
          "sender": "SENDER", 
          "price": 0.0642918, 
          "currency": "EUR", 
          "sent_at": "2022-04-18 11:00:30", 
          "created_at": "2022-04-18 10:55:35" 

        } 

      ] 

  } 

}

Можливі помилки

Отримати список сесій автентифікації

Використовується для отримання списку автентифікацій за період.

Щоб отримати список сесій автентифікації, зробіть запит на цей URL:

Будьте надійними. Використовуйте 2FA
Почати

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

Параметри відповіді

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

Відповідь у разі успішного запиту:

{
  "data": {
    "list": [
      {
      "id": "ea5db413-e368-4952-b745-cc2030210c49",
      "recipient": "380501403813",
      "status": "verified",
      "channel": "sms",
      "sender": "testsms",
      "sender_alt": "string",
      "message_text": "Your BSG 2FA confirmation code is {code}. Do not share this with anyone else.",
      "code_lifetime": 30,
      "code_max_tries": 5,
      "code_digits": 6,
      "price": 50.25,
      "currency": "EUR",
      "country_code": "FR",
      "expired_at": "2022-04-28 14:21:16",
      "created_at": "2022-04-28 14:21:16",
      "updated_at": "2022-04-28 14:21:16",
      "finished_at": "2022-04-28 14:21:16",
      "messages": [
        {
          "id": "1ed32701-5d4f-6cfa-ba06-9db3aa8bab68",
          "recipient": "61401629754",
          "status": "accepted",
          "channel": "sms",
          "sender": "SENDER",
          "price": 0.0642918,
          "currency": "EUR",
          "sent_at": "2022-04-18 11:00:30",
          "created_at": "2022-04-18 10:55:35"
        }
      ]
    },
    "total": 100
  }
}

Створити шаблон повідомлення

Цей метод створює новий шаблон повідомлення для надсилання OTP-коду.

Зверніть увагу: після створення шаблон проходить модерацію. Він буде доступний для надсилання повідомлень з OTP-кодом лише після модерації. Щойно шаблон буде готовий, його статус зміниться з Requested на Approved.

Щоб створити шаблон повідомлення, зробіть запит на цей URL:

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

Приклад запиту

{   

   "name": "template name",   

   "countries": ["UA","PT","AD","IT"],   

   "text": "test code is {code2fa}" 

}

Параметри відповіді

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

Відповідь у разі успішного запиту:

{

"data": {

     "template_id": 515,

     "name": "template name",

     "text": "test code is {code2fa}",

     "countries": [

             "AD",

             "IT",

             "PT",

             "UA"

           ],

     "status": "requested",

     "updated_at": "2023-06-30 14:52:58"

    }

}

Можливі помилки

Видалити шаблон повідомлення

Цей метод видаляє шаблон повідомлення для надсилання OTP-коду за його унікальним ідентифікатором.

Щоб видалити шаблон повідомлення, надішліть запит на цей URL:

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

Параметри відповіді

Якщо запит виконано успішно, повертається відповідь — Successfully removed.

Коди помилок

Отримати список шаблонів

Цей метод повертає список шаблонів повідомлень для надсилання OTP-коду з можливістю фільтрації за різними параметрами.

Щоб отримати список шаблонів, надішліть запит на цей URL:

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

Параметри відповіді

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

Відповідь у разі успішного запиту:

{

   "data": [

      {

         "template_id": "49",

         "name": "string",

         "countries": [

            "AD",

            "IT",

            "PT",

            "UA"

         ],

         "text": "Your BSG 2FA confirmation code is {code2fa}.",

         "status": "approved",

         "updated_at": "2022-04-18 10:55:35"

      }

   ],

   "total": 1,

   }

}

2FA errors:

Відповіді з помилками One API:

1.1. Термін дії коду доступу закінчився

1.2. Код доступу не знайдено

1.3. Статус автентифікації — скасовано

1.4. Термін дії автентифікації закінчився

1.5. Статус автентифікації — помилка

1.6. Недійсний статус автентифікації

1.7. Ліміт автентифікацій зі статусом pending

1.8. Загальний ліміт автентифікацій

1.9. Ліміт спроб перевірки автентифікації

1.10. Автентифікацію не знайдено

1.11. Ціну автентифікації не знайдено

1.12. Недостатньо коштів

1.13. Отримувач присутній у стоп-листі

1.14. Канал автентифікації неактивний

1.15. Канал автентифікації не знайдено

1.16. Шаблон не знайдено

1.17. Шаблон за замовчуванням не можна видалити

1.18. У користувача вже є шаблон з такою самою назвою!

1.19. Ця дія недоступна для облікового запису вашого типу.

1.20. Змінна {code2fa} має зустрічатися в тексті лише один раз

1.21. У тексті обовʼязково повинна бути змінна {code2fa}

1.22. Кількість запитів на створення шаблону обмежена 10. Дочекайтеся підтвердження від менеджера, перш ніж надсилати новий запит.

{
  "errors": [
    {
      "message": "ERROR_MESSAGE_1"
    }
  ]
}

2. Помилки валідації OneAPI:

{
  "message": "The given data was invalid.",
  "errors": {
    "<FIELD_1>": [
      "<VALIDATION_ERROR_1>"
    ], ...

    "<FIELD_N>": [
      "<VALIDATION_ERROR_N>"
    ]
  }
}

3. Помилки інтеграції OneAPI з 2FA:

3.1. Необроблена відповідь сервісу 2FA порожня.

3.2. Необроблена відповідь сервісу 2FA містить некоректний вміст.

3.3. Відповідь сервісу 2FA з помилкою порожня.

3.4. Структура відповіді сервісу 2FA з помилкою некоректна.

3.5. Помилка отримання відповіді-помилки від сервісу 2FA.

3.6. Помилка отримання успішної відповіді від сервісу 2FA.

3.7. Помилка отримання відповіді від сервісу 2FA.

3.8. Помилка сервісу 2FA.

3.9. Помилка отримання відповіді-помилки від сервісу 2FA.

3.10. Помилка отримання успішної відповіді від сервісу 2FA.

3.11. Помилка отримання відповіді від сервісу 2FA.

{
  "message": "<ERROR_MESSAGE>",
  "errors": [
    ...
  ]
}