PHONE-CONFIRM API

Статус документа

Оглавление

Цель и смысл

Данное API предназначено для подтверждения номера телефона пользователя.

Приоритетность каналов подтверждения номера телефона

• сервер оставляет за собой право самостоятельно выбирать приоритет каналов подтверждения.

Сценарии

1. SIM-Push

• Пользователю сначала отправляется SIM-Push уведомление — всплывающее окно на телефоне с текстом:
  “Для входа в приложение нажмите ‘Принять’” и кнопками “Принять” / “Отклонить”.
• Если уведомление не доставлено или пользователь нажал “Отклонить”, автоматически отправляется SMS с кодом подтверждения на тот же номер.
• Уведомление и SMS в рамках SIM-Push отправляются как единый способ подтверждения через одного провайдера.

2. Звонок пользователю (при ошибке с sim-push)

• Если SIM-Push (уведомление + SMS) не сработал, совершается звонок на номер пользователя.
• Звонок — отдельный способ подтверждения.
• Если звонок не прошёл, переходим к следующему этапу.

3. SMS после звонка (через другого провайдера)

• После неудачного звонка отправляется SMS с кодом подтверждения — через другого провайдера.
• Пользователь вводит код из SMS для подтверждения номера телефона.

4. Тех. поддержка.

• Если все каналы подтверждения исчерпаны, то есть использованы безуспешно, тогда приложению предложить пользователю обратиться в тех. поддержку для подтверждения номера телефона.

Повторные запросы

• Если пользователь нажимает кнопку “Мне не пришёл код” — инициируется повторный запрос подтверждения номера телефона, процесс начинается со следующего за предыдущим способа подтверждения.

Итоговая логика

Взаимодействие с API

API подразумевает доступ только аутентифицированного пользователя (возможно, анонимного), пользующегося авторизованным приложением.

Вследствие чего данное API должно быть доступно только по HTTPS. Формат запроса:

https://<path_to_api>/<api_version>/<method>

Где:

• path_to_api — путь до API, полученный в Регистратуре
• api_version — мажорная версия API (должна быть равна 2)
• method — метод, который производится над элементом

Коды ответов сервера должны соответствовать стандартным кодам HTTP-ответов для соответствующих ситуаций.

Коды ответов

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

Для аутентификации пользователя клиент должен передать полученный ранее токен доступа, выданный Auth API контрагента, по схеме аутентификации в соответствии с типом токена.

Для авторизации по типу токена “Bearer” рекомендуется использовать HTTP заголовок Authorization, пример:

Authorization: Bearer 18dasd81230dah12032

Методы

confirm - подтвердить номер телефона

Параметры:

Замечание: - phone должен содержать 11 цифр и первые две цифры должны начинаться с 79, +79, 89. То есть только сотовые российские номера

✅ Допустимый формат phone: - +79xxxxxxxx - 79xxxxxxxx - 89xxxxxxxx

Пример успешного взаимодействия

Запрос

POST /phoneconfirm/2/confirm
Authorization: Bearer 18dasd81230dah12032
Content-Type: application/json
Host: api.peers.tv

{
  "phone": "79997772222"
}

Ответ*

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "result": "ok",
  "request_id": "bded3728-3ddc-4db9-ab7f-16612f3e3494",
  "type": "sim-push",
  "code_input_required": "4_digit_code",
  "ttl": 900,
  "timeout": 60
}

Описание полей ответа

Возможные значения параметра type:

• sim-push — верификация через sim-push.
• call — верификация через звонок
• sms — верификация через смс

Пример ответа с ошибкой:

HTTP/1.1 200
Content-Type: application/json; charset=UTF-8

{
  "result": "error",
  "error": "delivery_failed"
}

verify - проверка статуса подтверждения номера телефона

Параметры:

Пример успешного взаимодействия

Запрос

POST /phoneconfirm/2/verify
Authorization: Bearer 18dasd81230dah12032
Content-Type: application/json
Host: api.peers.tv

{
  "request_id": "bded3728-3ddc-4db9-ab7f-16612f3e3494"
}

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

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
"result": "ok",
"status": "confirmed",
"code_input_required": "no_code",
"error_attempts": 0,
"max_attempts": 3,
"ttl": 90
}

Пример ответа с ошибкой

HTTP/1.1 200
Content-Type: application/json; charset=UTF-8

{
"result": "error",
"error": "request_id_expired"
}

Описание полей ответа

! Клиент обязан сохранять предыдущий ответ API при status: "unconfirmed" !

Это требуется для корректной обработки сценариев: - Сравнения изменений между последовательными запросами verify - Отслеживания динамики параметров (error_attempts, code_input_required) - Принятия решений о переходе между экранами приложения

Сценарий использования метода verify

🔹 1. Успешное подтверждение номера телефона через sim-push

Параметры ответа:

{
  "result": "ok",
  "status": "confirmed",
  "code_input_required": "no_code",
  "error_attempts": 0,
  "max_attempts": 3,
  "ttl": 90
}

Действия от клиента:

• Номер телефона успешно подтвержден
• Дальнейшие действия не требуются

🔹 2. Номер телефона не подтвержден по sim-push

Параметры ответа:

{
  "result": "ok",
  "status": "unconfirmed",
  "code_input_required": "no_code",
  "error_attempts": 0,
  "max_attempts": 3,
  "ttl": 90,
}

Действия от клиента:

• вывести экран об уведомлении согласно дизайну
• Приложение продолжает отправлять запросы на verify
• Цикл продолжается пока:
• Не истечет ttl
• Статус не изменится на confirmed
• Параметр code_input_required не изменится на 4_digit_code
• пока пользователь не изменит канал доставки кода

🔹 3. Требуется ввод кода

Параметры ответа:

{
  "result": "ok",
  "status": "unconfirmed",
  "code_input_required": "4_digit_code",
  "error_attempts": 0,
  "max_attempts": 3,
  "ttl": 90
}

Действия от клиента:

• Приложение отображает экран для ввода 4-значного кода
• Пользователь вводит полученный код
• Приложение отправляет код методом checkCode

🔹 4. Повторная проверка статуса, если текущий ответ не изменился по сравнению с предыдущим

Параметры ответа:

{
  "result": "ok",
  "status": "unconfirmed",
  "code_input_required": "4_digit_code",
  "error_attempts": 0,
  "max_attempts": 3,
  "ttl": 90
}

Действия от клиента:

• Приложение продолжает периодически отправлять запросы на verify
• Цикл продолжать пока не появится измененный ответ от бекенда

🔹 5. Неверный код подтверждения. error_attempts увеличился

Параметры ответа:

{
  "result": "ok",
  "status": "unconfirmed",
  "code_input_required": "4_digit_code",
  "error_attempts": 1, // увеличилось. Приложению  нужно запомнить предыдущий ответ и сравнивать с новым. При увелечении приложению нужно уведомить пользователю о невалидном коде и предложить ввести код заново
  "max_attempts": 3,
  "ttl": 90
}

Действия клиента:

• Приложение отображает сообщение об ошибке (согласно дизайну)
• Предлагает пользователю ввести код повторно

checkCode - отправка кода.

Параметры:

Пример успешного взаимодействия

Запрос

POST /phoneconfirm/2/checkCode
Authorization: Bearer 18dasd81230dah12032
Content-Type: application/json
Host: api.peers.tv

{
  "request_id": "bded3728-3ddc-4db9-ab7f-16612f3e3494",
  "code": "1234"
}

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

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
"result": "ok"
}

Пример ответа с ошибкой

HTTP/1.1 200
Content-Type: application/json; charset=UTF-8

{
"result": "error",
"error": "max_attempts_check_code"
}

Описание полей ответа

Все возможные значения status

Все возможные значения result

Все возможные значения code_input_required для всех методов

Список всех возможных значений для параметра error для всех методов