Параметр | Значение | Описание |
service_id * | Цифровое значение | ID вами созданного сервиса, более подробное описание в Определение понятий -> 2.3 |
key * | Строка, 32 символа | Секретный ключ вашего сервиса, более подробное описание в Определение понятий -> 2.4 |
phone * | Цифровое значение Без + с кодом страны |
Номер телефона вашего пользователя, которому будет совершен звонок с авторизацией |
code | Цифровое значение 4 цифры |
На эти 4 цифры будет заканчиваться исходящий от нас звонок к вашему пользователю. Если `code` не передан, он будет автоматически сгенерирован нами |
client | Набор символов До 64 символов |
Можете передать информацию о вашем пользователе, например его никнейм, E-mail и так далее. В статистике сервиса сможете найти ту или иную авторизацию по этому параметру. |
unique | Набор символов До 64 символов |
Для активации идемпотентности запроса. Рекомендуем использовать V4 UUID. Более подробное описание в Определение понятий -> 2.5 |
$service_id = 1692;
$secret_key = "rjE9LoomXNr5SXaAU0OUSjeG69rsEMNV";
$client_phone = 79991234567;
$code = 7777;
$request = file_get_contents('https://api.ucaller.ru/v1.0/initCall?service_id='.$service_id.'&key='.$secret_key.'&phone='.$client_phone.'&code='.$code);
$request = json_decode($request, true);
if($request['status'] == true) { // Подробнее о том, какой ответ мы возврашаем в случае успеха, мы описываем ниже
/*
Авторизация успешно инициализирована
Мы совершаем звонок на номер +79991234567
Последние четыре цифры номера, с которого мы совершаем звонок, заканчиваются на 7777
*/
}
Пример нашего ответа в формате JSON:
{
"status": true, // true в случае успеха, false в случае неудачи
"ucaller_id": 103000, // уникальный ID в системе uCaller, который позволит проверять статус и инициализировать метод initRepeat
"phone": 79991234567, // номер телефона, куда мы совершили звонок
"code": 7777, // код, который будет последними цифрами в номере телефона
"client": "nickname", // идентификатор пользователя переданный клиентом
"unique_request_id": "f32d7ab0-2695-44ee-a20c-a34262a06b90", // появляется только если вами был передан параметр `unique`
"exists": true // появляется при переданном параметре `unique`, если такой запрос уже был инициализирован ранее
}
Параметр | Значение | Описание |
service_id * | Цифровое значение | ID вами созданного сервиса, более подробное описание в Определение понятий -> 2.3 |
key * | Строка, 32 символа | Секретный ключ вашего сервиса, более подробное описание в Определение понятий -> 2.4 |
uid * | Цифровое значение | uCaller ID переданный нами в запросе initCall |
$service_id = 1692;
$secret_key = "rjE9LoomXNr5SXaAU0OUSjeG69rsEMNV";
$ucaller_id = 103000;
$request = file_get_contents('https://api.ucaller.ru/v1.0/initRepeat?service_id='.$service_id.'&key='.$secret_key.'&uid='.$ucaller_id);
$request = json_decode($request, true);
if($request['status'] == true) { // Подробнее о том, какой ответ мы возврашаем в случае успеха, мы описываем ниже
/*
Повторная бесплатная авторизация успешно инициализирована
*/
}
Пример нашего ответа в формате JSON:
{
"status": true,
"ucaller_id": 103001,
"phone": 79991234567,
"code": 7777,
"client": "nickname",
"unique_request_id": "f32d7ab0-2695-44ee-a20c-a34262a06b90",
"exists": true
"free_repeated": true // показывает, что осуществлена повторная авторизация
}
Параметр | Значение | Описание |
service_id * | Цифровое значение | ID вами созданного сервиса, более подробное описание в Определение понятий -> 2.3 |
key * | Строка, 32 символа | Секретный ключ вашего сервиса, более подробное описание в Определение понятий -> 2.4 |
uid * | Цифровое значение | uCaller ID переданный нами в запросе initCall |
$service_id = 1692;
$secret_key = "rjE9LoomXNr5SXaAU0OUSjeG69rsEMNV";
$ucaller_id = 103000;
$request = file_get_contents('https://api.ucaller.ru/v1.0/getInfo?service_id='.$service_id.'&key='.$secret_key.'&uid='.$ucaller_id);
$request = json_decode($request, true);
if($request['status'] == true) { // Подробнее о том, какой ответ мы возврашаем в случае успеха, мы описываем ниже
/*
Получили информацию по uCaller ID
*/
}
Пример нашего ответа в формате JSON:
{
"status": true, // true в случае успеха, false в случае неудачи
"ucaller_id": 103000, // запрошенный uCaller ID
"init_time": 1556617525, // время, когда была инициализирована авторизация
"call_status": -1, // Статус звонка, -1 = информация проверяется (от 1 сек до 1 минуты), 0 = дозвониться не удалось, 1 = звонок осуществлен
"is_repeated": false, // является ли этот uCaller ID повтором (initRepeat), если да, будет добавлен first_ucaller_id с первым uCaller ID этой цепочки
"repeatable": false, // возможно ли инициализировать бесплатные повторы (initRepeat)
"repeat_times": 2, // Появляется в случае repeatable: true, говорит о количестве возможных повторов
"repeated_ucaller_ids": [103001, 103002], // цепочка uCaller ID инициализированных повторов (initRepeat)
"unique": "f32d7ab0-2695-44ee-a20c-a34262a06b90", // ключ идемпотентности (если был передан)
"client": "nickname", // идентификатор пользователя переданный клиентом (если был передан)
"phone": 79991234567, // номер телефона пользователя, куда мы совершали звонок
"code": 7777, // код авторизации
"country_code": "RU", // ISO код страны пользователя
"country_image": "https://static.ucaller.ru/flag/ru.svg", // изображение флага страны пользователя
"phone_info": [ // информация по телефону, информация может отличаться от примера
{
"operator": "МТС", // Оператор связи
"region": "Республика Татарстан", // регион субъеккта Российской федерации
"mnp": "Мегафон" // Если у номера был сменен оператор - MNP покажет нового оператора
}
],
"cost": 0.3 // сколько стоила эта авторизация клиенту
}
Параметр | Значение | Описание |
service_id * | Цифровое значение | ID вами созданного сервиса, более подробное описание в Определение понятий -> 2.3 |
key * | Строка, 32 символа | Секретный ключ вашего сервиса, более подробное описание в Определение понятий -> 2.4 |
$service_id = 1692;
$secret_key = "rjE9LoomXNr5SXaAU0OUSjeG69rsEMNV";
$request = file_get_contents('https://api.ucaller.ru/v1.0/getBalance?service_id='.$service_id.'&key='.$secret_key);
$request = json_decode($request, true);
if($request['status'] == true) { // Подробнее о том, какой ответ мы возврашаем в случае успеха, мы описываем ниже
/*
Информация по балансу получена успешно
*/
}
Пример нашего ответа в формате JSON:
{
"status": true, // true в случае успеха, false в случае неудачи
"rub_balance": 84.6, // Остаточный баланс на рублевом счете аккаунта
"bonus_balance": 0, // Остаточный бонусный баланс
"tariff": "startup", // Кодовое значение вашего тарифного плана
"tariff_name": "Старт-ап" // Название тарифного плана
}
Параметр | Значение | Описание |
service_id * | Цифровое значение | ID вами созданного сервиса, более подробное описание в Определение понятий -> 2.3 |
key * | Строка, 32 символа | Секретный ключ вашего сервиса, более подробное описание в Определение понятий -> 2.4 |
$service_id = 1692;
$secret_key = "rjE9LoomXNr5SXaAU0OUSjeG69rsEMNV";
$request = file_get_contents('https://api.ucaller.ru/v1.0/getService?service_id='.$service_id.'&key='.$secret_key);
$request = json_decode($request, true);
if($request['status'] == true) { // Подробнее о том, какой ответ мы возврашаем в случае успеха, мы описываем ниже
/*
Информация по сервису получена успешно
*/
}
Пример нашего ответа в формате JSON:
{
"status": true, // true в случае успеха, false в случае неудачи
"service_status": 1692, // ID сервиса
"name": "ВКонтакте", // Название сервиса
"creation_time": 1556064401, // Время создания сервиса в unix формате
"last_request": 1556707453, // Время последнего не кэшированного обращения к API сервиса в unix формате
"owner": "[email protected]", // E-mail адрес владельца сервиса
"use_direction": "ВКонтакте приложение", // Информация о том, где будет использоваться сервис
"now_test": true, // Состояние тестового режима на текущий момент
"test_info": {
"test_requests": 89, // Оставшееся количество бесплатных тестовых обращений
"verified_phone": 79991234567 // Верифицированный номер телефона для тестовых обращений
}
}
</head>
вашего сайта
<script src="https://widget.ucaller.ru/widget.min.js"></script>
<div data-ucaller="публичный ключ
" data-hash='<?php echo $hash; ?>'></div>
Для успешной инициализации виджета, требуется собрать $hash
, который обеспечит безопасность передаваемых значений, сделаем это до этого HTML кода, на примере PHP реализации:
$secret_key = "Tmm5ZXM11vPmJp1OiuaY7gatAT5ggOl1"; // Секретный ключ вашего виджета
$public_key = "mnM3717euMAGCphIeikXtsmeet6oTK97"; // Публичный ключ вашего виджета
$phone_number = ""; // Если требуется указать номер телефона по-умолчанию (открытый или закрытый)
$hash = hash("sha256", $public_key.$phone_number.$secret_key);
Теперь наш виджет будет инициализирован и готов к работе.Атрибут | Описание |
data-ucaller | Обязательный атрибут, содержащий в себе публичный ключ виджета |
data-hash | Обязательный атрибут, собирается методом конкатенации в хэш sha-256публичный ключ + номер телефона или идентификатор по-умолчанию (если есть) + секретный ключ , пример реализации на языке PHP смотрите выше |
data-phone | Номер телефона по-умолчанию, пользователь не сможет изменить его Формат номера 79991234567, номер будет виден пользователю в открытую |
data-phone-id | Идентификатор номера пользователя формата 4367a01f726e4b81, который можно получить через методы initCall и verifyResponse В таком случае не передается data-phone, и номер будет скрыт, пример +*******4567 |
data-phone
и data-phone-id
добавлять не нужно.data-phone
или data-phone-id
заполнены, то при формировании подписи между публичным и секретным ключами, используется либо значение из data-phone
, либо из data-phone-id
.data-phone
и data-phone-id
, то приоритет будет у data-phone
, и именно его мы будем ожидать в подписи data-hash
.data-phone
и data-phone-id
не нужно, подпись будет фомироваться только используя значения публичный ключ + секретный ключ
.
<?php
$widget_id = 998; // Идентификатор виджета, требуется для обращения к Widget API
$secret_key = "Tmm5ZXM11vPmJp1OiuaY7gatAT5ggOl1"; // Секретный ключ виджета
$public_key = "mnM3717euMAGCphIeikXtsmeet6oTK97"; // Публичный ключ виджета
$hash = hash("sha256", $public_key.$secret_key);
if($_POST["register"]) {
if($_POST["ucaller-response"]) { // После успешной верификации номера телефона в виджете, мы автоматически добавляем поле в вашу форму с именем `ucaller-response`
// Описание взаимодействия с Widget API описано в пункте 5.1
// Здесь мы проверяем, действительно ли пользователь прошел верификацию номера телефона
$response = file_get_contents("https://api.ucaller.ru/v1.0/verifyResponse?service_id=".$widget_id."&key=".$secret_key."&response=".$_POST["ucaller-response"]);
$response = json_decode($response, true);
if($response["status"]) {
// Все верно! Этот пользователь проходил верификацию номера
$phone_number = $response["phone"]; // Может получить номер телефона пользователя
$phone_id = $response["phone"]; // Может получить идентификатор номера телефона
// Регистрируем пользователя!
echo "Вы успешно зарегистрированы!";
}
else echo "Нет, вы передали неверные значения, попробуйте повторить попытку верификации номера в виджете";
}
else echo "Вам необходимо пройти проверку номера телефона";
}
?>
<html>
<head>
<title>Регистрация на сайте</title>
<script src="https://widget.ucaller.ru/widget.min.js"></script>
</head>
<body >
<form method="post">
Ваше имя:
<input type="text" name="some-input" />
Подтвердите номер телефона:
<div data-hash='<?php echo $hash; ?>' data-ucaller="<?php echo $public_key; ?>"></div>
Нажмите на кнопку:
<input type="submit" name="register" value="Регистрация" />
</form>
</body>
</html>
<?php
$widget_id = 998; // Идентификатор виджета, требуется для обращения к Widget API
$secret_key = "Tmm5ZXM11vPmJp1OiuaY7gatAT5ggOl1"; // Секретный ключ виджета
$public_key = "mnM3717euMAGCphIeikXtsmeet6oTK97"; // Публичный ключ виджета
$phone_number = "79991234567"; // Номер телефона без + в международном формате
$hash = hash("sha256", $public_key.$phone_number.$secret_key);
if($_POST["register"]) {
if($_POST["ucaller-response"]) { // После успешной верификации номера телефона в виджете, мы автоматически добавляем поле в вашу форму с именем `ucaller-response`
// Описание взаимодействия с Widget API описано в пункте 5.1
// Здесь мы проверяем, действительно ли пользователь прошел верификацию номера телефона
$response = file_get_contents("https://api.ucaller.ru/v1.0/verifyResponse?service_id=".$widget_id."&key=".$secret_key."&response=".$_POST["ucaller-response"]);
$response = json_decode($response, true);
if($response["status"]) {
// Все верно! Этот пользователь проходил верификацию номера
$phone_number = $response["phone"]; // Может получить номер телефона пользователя
$phone_id = $response["phone"]; // Может получить идентификатор номера телефона
// Регистрируем пользователя!
echo "Вы успешно зарегистрированы!";
}
else echo "Нет, вы передали неверные значения, попробуйте повторить попытку верификации номера в виджете";
}
else echo "Вам необходимо пройти проверку номера телефона";
}
?>
<html>
<head>
<title>Регистрация на сайте</title>
<script src="https://widget.ucaller.ru/widget.min.js"></script>
</head>
<body >
<form method="post">
Ваше имя:
<input type="text" name="some-input" />
Подтвердите номер телефона:
<div data-hash='<?php echo $hash; ?>' data-phone='<?php echo $phone_number; ?>' data-ucaller="<?php echo $public_key; ?>"></div>
Нажмите на кнопку:
<input type="submit" name="register" value="Регистрация" />
</form>
</body>
</html>
<?php
$widget_id = 998; // Идентификатор виджета, требуется для обращения к Widget API
$secret_key = "Tmm5ZXM11vPmJp1OiuaY7gatAT5ggOl1"; // Секретный ключ виджета
$public_key = "mnM3717euMAGCphIeikXtsmeet6oTK97"; // Публичный ключ виджета
$phone_number_id = "a35b95745de1e289"; // ID номера телефона
$hash = hash("sha256", $public_key.$phone_number_id.$secret_key);
if($_POST["register"]) {
if($_POST["ucaller-response"]) { // После успешной верификации номера телефона в виджете, мы автоматически добавляем поле в вашу форму с именем `ucaller-response`
// Описание взаимодействия с Widget API описано в пункте 5.1
// Здесь мы проверяем, действительно ли пользователь прошел верификацию номера телефона
$response = file_get_contents("https://api.ucaller.ru/v1.0/verifyResponse?service_id=".$widget_id."&key=".$secret_key."&response=".$_POST["ucaller-response"]);
$response = json_decode($response, true);
if($response["status"]) {
// Все верно! Этот пользователь проходил верификацию номера
$phone_number = $response["phone"]; // Может получить номер телефона пользователя
$phone_id = $response["phone"]; // Может получить идентификатор номера телефона
// Регистрируем пользователя!
echo "Вы успешно зарегистрированы!";
}
else echo "Нет, вы передали неверные значения, попробуйте повторить попытку верификации номера в виджете";
}
else echo "Вам необходимо пройти проверку номера телефона";
}
?>
<html>
<head>
<title>Регистрация на сайте</title>
<script src="https://widget.ucaller.ru/widget.min.js"></script>
</head>
<body >
<form method="post">
Ваше имя:
<input type="text" name="some-input" />
Подтвердите номер телефона:
<div data-hash='<?php echo $hash; ?>' data-phone-id='<?php echo $phone_number_id; ?>' data-ucaller="<?php echo $public_key; ?>"></div>
Нажмите на кнопку:
<input type="submit" name="register" value="Регистрация" />
</form>
</body>
</html>
ucaller-response
.ucaller-response
, которое вы должны проверить используя этот метод. Параметр | Значение | Описание |
service_id * | Цифровое значение | ID вами созданного виджета, более подробное описание в Определение понятий -> 2.3 |
key * | Строка, 32 символа | Секретный ключ вашего виджета, более подробное описание в Определение понятий -> 2.4 |
response * | Набор символов | Это значение будет добавлено в вашу форму после успешной авторизации номера телефона в виджете |
ucaller-response
можно проверить только один раз.ucaller-response
, с вашего баланса будут списаны средства в соответствии с вашим тарифом.
// Примеры запросов указаны в 4.2 Различные примеры реализации виджета на странице
Пример нашего ответа в формате JSON:
{
"status": true, // true в случае успеха, false в случае неудачи
"service_id": 998, // id вашего виджета
"call_init": 1557950216, // время, когда верификация номера была начата
"phone": 79991234567, // номер телефона пользователя
"phone_id": "8beff3c368652947", // идентификатор номера
"ip": "127.0.0.1", // IP с которого была осуществлена авторизация
"ucaller_id": 103493, // уникальный ID в системе uCaller, который позволит проверять статус и инициализировать метод initRepeat
"success_time": 1557950220 // время, когда верификация номера была завершена успешно
}
Код ошибки | Описание |
0 | Ваш IP адрес заблокирован |
1 | Не переданы какие-либо требуемые GET параметры |
2 | Неверная комбинация GET параметров `service_id` и `key` |
3 | Возникла ошибка при инициализации авторизации (неверный номер телефона или тех. работы) |
4 | Работа вашего сервиса отключена в настройках |
5 | [Тестовый режим] Вы не прошли верификацию номера телефона в личном кабинете |
6 | [Тестовый режим] Баланс бесплатных суточных тестовых авторизаций исчерпан |
7 | [Тестовый режим] Переданный GET параметр `phone` не разрешен (на него не пройдена верификация) |
8 | Проверьте максимально допустимую длину передаваемых значений |
9 | Авторизация для этой страны запрещена настройками географии работы в личном кабинете |
10 | Этот uCaller id не существует или у вас нет к нему доступа |
11 | Авторизация не может быть бесплатно повторена, время истекло |
12 | Авторизация не может быть бесплатно повторена, лимит исчерпан |
13 | Ошибочная попытка бесплатной инициализации повторной авторизации |
14 | [Widget] Неверный формат переданного `ucaller-response` |
15 | [Widget] Такого ответа `ucaller-response` не существует |
16 | [Widget] Виджет отключен в настройках |
17 | [Widget] Ключи виджета нельзя использовать для API Classic |
18 | Достигнут лимит в 4 исходящих звонка в минуту или 15 вызовов в день для одного номера |
1000 | Этот метод API временно недоступен |
1001 | Ваш аккаунт заблокирован |
1002 | Недостаточно средств на балансе аккаунта |
1003 | С этого IP запрещено обращаться к API этого сервиса |
1004 | Сервис заархивирован |