Аутентификация

Сервис аутентификации Besoft Cloud позволяет подтвердить, что номер телефона действительно принадлежит пользователю. Принцип простой:

1. Ваш сервер вызывает send-otp — мы отправляем 4-значный код на телефон пользователя.
2. Пользователь вводит код в вашем приложении.
3. Ваш сервер вызывает verify-otp с этим кодом — мы проверяем и отвечаем «верно» или «неверно».

Стоимость списывается с баланса вашего проекта только при успешной верификации.

Чтобы пользоваться API, нужны два ключа проекта:

• public_key — публичный идентификатор проекта, передаётся в query-параметре _project_key.
• secret_key — секрет, передаётся в заголовке Authorization: Bearer …. Хранится только на сервере.

Получить ключи можно в личном кабинете — в разделе настроек проекта. Перед использованием активируйте сервис authentication для проекта.

Базовый URL для всех запросов:

https://api.cloud.besoft.kg

Все ответы возвращаются в JSON одинакового формата:

{
  "status": "success",
  "result": 0,
  "payload": { ... }
}

• status — строковый код результата. Для успешных ответов всегда "success"; для ошибок — машиночитаемый код (см. раздел «Ошибки»).
• result — 0 при успехе, -1 или 1 при ошибке.
• payload — данные ответа или подробности об ошибке.

Каждый запрос к /tp/v1/* должен содержать оба ключа:

POST /tp/v1/authentication/send-otp?_project_key=YOUR_PUBLIC_KEY
Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json

Если ключи неверны или сервис authentication не активирован — вернётся ошибка project_is_required с HTTP 403.

Минимальный сценарий: отправить код → проверить код. Замените YOUR_PUBLIC_KEY и YOUR_SECRET_KEY на ваши значения.

Шаг 1. Отправка OTP

curl -X POST 'https://api.cloud.besoft.kg/tp/v1/authentication/send-otp?_project_key=YOUR_PUBLIC_KEY' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "996777171171"
  }'

В ответе вы получите payload.token — сохраните его, чтобы потом верифицировать OTP, который введёт пользователь.

Шаг 2. Верификация OTP

curl -X POST 'https://api.cloud.besoft.kg/tp/v1/authentication/verify-otp?_project_key=YOUR_PUBLIC_KEY' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "TOKEN_FROM_SEND_OTP",
    "otp": "1234"
  }'

Отправка OTP-кода на телефон пользователя.

Тело запроса

• phone_number

  Тип

  string

  Обязат.

  да

  Описание

  Номер телефона в формате E.164 без + (например, 996777171171). + в начале допускается и обрезается.

• channels

  Тип

  string[]

  Обязат.

  нет

  Описание

  Желаемые каналы в порядке приоритета. Учитываются только вместе с respect_channels: true. См. раздел «Каналы».

• respect_channels

  Тип

  boolean

  Обязат.

  нет

  Описание

  true — отправить строго в каналы из channels, без автоматического выбора и без запасного канала.

// Автоматический выбор канала (по умолчанию)
{
  "phone_number": "996777171171"
}

// Строго по SMS
{
  "phone_number": "996777171171",
  "channels": ["sms"],
  "respect_channels": true
}

Успешный ответ

{
  "status": "success",
  "result": 0,
  "payload": {
    "id": 12345,
    "token": "a1b2c3d4e5f6...",        // 64-символьный токен, нужен для verify-otp
    "message": {
      "id": 67890,
      "internal_id": "uuid"
    },
    "channel": "WHATSAPP",              // фактически использованный канал
    "phone_number": "996777171171",
    "expires_at": "2025-05-28T14:35:00",
    "is_test": false,                   // true, если номер из списка тестовых
    "attempts_left": 5                  // сколько попыток ввода OTP осталось
  }
}

Возможные ошибки

• invalid_channels

  HTTP

  422

  Когда

  respect_channels: true, но в channels нет ни одного поддерживаемого канала (whatsapp_business, sms).

• sms_not_available_for_country

  HTTP

  422

  Когда

  respect_channels: true, в channels есть sms, а номер не из Кыргызстана (996…).

Проверка, есть ли WhatsApp на указанном номере. Полезно перед выбором канала: если WhatsApp нет — отправляйте сразу SMS.

Тело запроса

• phone_number

  Тип

  string

  Обязат.

  да

  Описание

  Номер телефона. + в начале допускается.

{
  "phone_number": "996777171171"
}

Успешный ответ

{
  "status": "success",
  "result": 0,
  "payload": {
    "phone_number": "996777171171",
    "has_whatsapp": true
  }
}

Возможные ошибки

• no_connected_whatsapp_instances

  HTTP

  503

  Когда

  Сейчас нет ни одного подключённого WhatsApp-инстанса для проверки. Повторите запрос позже или используйте send-otp с fallback-каналом.

• whatsapp_gateway_unreachable

  HTTP

  502

  Когда

  WhatsApp-шлюз недоступен (сеть/таймаут).

Проверка кода, который ввёл пользователь. Стоимость верификации списывается с баланса проекта только при успехе.

Тело запроса

• token

  Тип

  string

  Обязат.

  да

  Описание

  Токен, полученный из send-otp.

• otp

  Тип

  string

  Обязат.

  да

  Описание

  4-значный код, введённый пользователем.

{
  "token": "a1b2c3d4e5f6...",
  "otp": "1234"
}

Успешный ответ (HTTP 200)

{
  "status": "success",
  "result": 0,
  "payload": {
    "attempts_left": 4,
    "phone_number": "996777171171"
  }
}

Неверный OTP (HTTP 401)

{
  "status": "invalid_otp",
  "result": -1,
  "payload": {
    "attempts_left": 3,
    "phone_number": "996777171171"
  }
}

Когда attempts_left доходит до нуля — токен становится невалидным, нужно начинать заново с send-otp.

По умолчанию канал выбирается автоматически, поле channels игнорируется: если у номера есть WhatsApp — код уходит в WhatsApp с резервным SMS, если нет — по SMS.

С respect_channels: true используются ровно те каналы, что переданы в channels, в указанном порядке. Запасной канал не добавляется: ["sms"] — только SMS, ["whatsapp_business"] — только WhatsApp. Неподдерживаемые значения отбрасываются.

• whatsapp_business

  Описание

  WhatsApp Business. Работает для любой страны, если у номера есть WhatsApp.

• sms

  Описание

  SMS. Только для номеров Кыргызстана (996…).

В личном кабинете в настройках сервиса authentication вы можете добавить тестовые номера в поле test_phone_numbers:

{
  "test_phone_numbers": [
    { "phone_number": "996700000001", "otp": "1234" },
    { "phone_number": "996700000002", "otp": "9999" }
  ]
}

При отправке OTP на такой номер:

• сообщение реально не отправляется;
• OTP всегда фиксированный, как указано в настройках;
• в ответе будет is_test: true;
• баланс проекта не списывается.

Используйте для разработки и для прохождения модерации в App Store / Google Play.

• За send-otp списывается стоимость сообщения по тарифу выбранного канала.
• За verify-otp списывается verified_account_price только при успешной проверке.
• check-whatsapp — бесплатный, баланс не списывается.
• Если баланс ниже balance_notify, вам придёт уведомление.
• Если баланс исчерпан, запросы вернут not_enough_balance (HTTP 402).

При ошибке поле status содержит машиночитаемый код. Используйте его для разветвления логики на клиенте, а не HTTP-код.

• project_is_required

  HTTP

  403

  Описание

  Неверный _project_key или secret_key, либо проект не найден.

• service_is_not_active

  HTTP

  403

  Описание

  Сервис authentication не активирован для проекта.

• not_enough_balance

  HTTP

  402

  Описание

  На балансе проекта недостаточно средств.

• not_enough_params

  HTTP

  403

  Описание

  Не передано обязательное поле в теле запроса.

• invalid_params

  HTTP

  403

  Описание

  Поле передано, но некорректного формата.

• assertion_error

  HTTP

  403

  Описание

  Не пройдена валидация (например, OTP не той длины).

• phone_number_has_no_whatsapp

  HTTP

  401

  Описание

  У номера нет WhatsApp, а fallback-канала не предоставлено.

• no_connected_whatsapp_instances

  HTTP

  503

  Описание

  В check-whatsapp: нет подключённых WhatsApp-инстансов для проверки. Повторите запрос позже.

• whatsapp_gateway_unreachable

  HTTP

  502

  Описание

  WhatsApp-шлюз недоступен (сеть/таймаут).

• not_found

  HTTP

  404

  Описание

  Токен не найден или уже истёк.

• invalid_otp

  HTTP

  401

  Описание

  Неверный OTP. См. payload.attempts_left.