Password Call — авторизация по коду

108 просмотра

Создано 02.03.2026

Обновлено 12.11.2026

Метод POST /api/v2/protected/auth/password-call расположен в разделе «Интеграции» → «Методы API» → «Авторизация».

📞 Назначение метода

Метод позволяет выполнить авторизацию пользователя с помощью телефонного звонка.

После ответа на входящий вызов пользователь услышит голосовое сообщение с кодом подтверждения. Этот код используется для привязки телефонного звонка к API-запросу.

Особенности работы

✅ Подключать номера телефонов в личном кабинете не требуется.

✅ Звонки выполняются с номеров MCN Telecom.

✅ Для абонента звонок является бесплатным.

📩 Запрос

{
"phoneNumber": "79311234567",
"verificationCode": "1234",
"lang": "ru-RU",
"isWithRedirect": false,
"marking": false
}

Параметр	Описание
phoneNumber	Номер куда поступит звонок.
verificationCode	Код подтверждения, который будет озвучен пользователю.
lang	Язык
isWithRedirect	Проверять ли номер получателя на переадресацию в ВАТС МСН. Результат проверки сервис отдаёт в ответе.
marking	Отправить звонок с номера к которому применена маркировка.

📨 Ответ на запрос

После успешного выполнения метода возвращается ответ:

{
  "ok": true,
  "verification_code": "123456",
  "verification_uuid": "e18dza6f7607_143456"
}

Описание параметров ответа

Параметр	Описание
`ok`	Результат выполнения запроса
`verification_code`	Код подтверждения, который будет озвучен пользователю
`verification_uuid`	Уникальный идентификатор звонка для дальнейшего сопоставления с событиями и веб-хуками

📋 Просмотр результата звонка

Информация о выполненном звонке доступна в разделе «Логи».

Пример события:

{
  "eventType": "PasswordCall",
  "accountId": 139245,
  "code": "1 2 3 4",
  "uuid": "ff27d2c64d23_139245",
  "lang": "ru-RU",
  "finalStatus": "ANSWER",
  "channel": "SIP/mcn-ast-215-00116521",
  "callerNumber": "73462390136",
  "event": "task.target-call-result.completed",
  "calledNumber": "79311110781",
  "q931Status": "16",
  "timestamp": "2026-11-12T04:41:21.772Z",
  "callId": "120-1794458463.13570044",
  "redirect": false,
  "linkedId": "120-1794458463.13570039",
  "dateReceivedAtUTC": "2026-11-12 04:41:14.644",
  "uniqueId": "120-1794458463.13570044",
  "duration": 6,
  "vpbxId": "15613",
  "marking": false
}

🔗 Связь запроса и звонка

Для сопоставления API-запроса и результата звонка используются поля:

Поле ответа API	Поле события
`verification_uuid`	`uuid`
`verification_code`	`code`

📊 Статусы верификационного звонка

✅ Звонок успешно принят

{
  "q931Status": 16,
  "finalStatus": "ANSWER"
}

☎️ Номер занят

{
  "q931Status": 17,
  "finalStatus": "CANCEL"
}

⏳ Звонок не был принят

{
  "q931Status": 16,
  "finalStatus": "CANCEL"
}

🚫 Вызов отклонён встречным оператором

Ошибка прохождения вызова через сеть ОКС-7.

{
  "q931Status": 31
}

💳 Ошибка биллинга

Звонок не выполнен из-за ограничений биллинговой системы.

{
  "q931Status": 41
}

❌ Номер недоступен

Любое значение q931Status, отличное от:

16
17
31

считается признаком недоступности номера.

🔔 Получение результата через веб-хук

Для автоматического получения информации о звонке необходимо создать подписку на событие Password Call.

Для этого перейдите в раздел «Интеграции → Веб-хуки» и создайте новую подписку.

В поле «Тело запроса» необходимо указать JSON-массив с перечнем переменных, которые будут передаваться на ваш URL.

Подробное описание формата событий и журналов вызовов приведено в разделе «Логи».

Пример сценария работы

Клиент вызывает метод passwordcall.
API возвращает verification_uuid и verification_code.
Пользователь принимает звонок и получает код подтверждения.
Система формирует событие Password Call.
Результат звонка сохраняется в разделе «Логи» и при необходимости отправляется на настроенный веб-хук.
По полю verification_uuid можно сопоставить событие с исходным API-запросом.

🆘 Поддержка и помощь
❓ Заявки в техническую поддержку | 📚 База знаний MCN Telecom | ☎️ +7 (495) 109-94-98 | 📧 info@mcn.ru