Запрос управления номером телефона – это набор API‑методов, позволяющих автоматизировать весь жизненный цикл телефонного номера: поиск, резервирование, бронирование, продажу, отруливание, возврат в свободный пул и т. д. Данные операции реализованы в сервисе Numbering API компании Plusofon.

Что такое запрос управления номером телефона?

В контексте современных телеком‑операторов запрос управления номером – это JSON‑RPC‑вызов, отправляемый на endpoint https://did-api.plusofon.ru/. Через него клиент (например, ваш CRM‑сервис) может выполнять любые операции над телефонными номерами, не прибегая к ручному вводу в веб‑интерфейсе.

• Подключение к API – метод connect (получение session‑id).
• Поиск номеров – метод search_numbers.
• Резервирование – reserv_numbers.
• Бронирование – book_numbers.
• Продажа – sell_numbers.
• Отруливание (установка на оборудование) – install_numbers.
• Возврат в свободный пул – return_numbers.
• Перемещение в «отстойник» и вывод из него – buffer_numbers, detach_numbers.

Все методы работают в рамках сессии, срок действия которой – 1 час. По истечении времени необходимо заново выполнить connect.

Основные функции API

2.1 Подключение (connect)

{
 "jsonrpc": "2.0",
 "method": "connect",
 "params": ["<login>", "<password>"],
 "id": 1
}

Ответ содержит session-id, который передаётся в последующих запросах.

2.2 Поиск номеров (search_numbers)

{
 "jsonrpc": "2.0",
 "method": "search_numbers",
 "params": [
 "<session-id>",
 {
 "city_code": ["495", "812"],
 "access_state": ["free"],
 "phone_number": "123"
 },
 0,
 50
 ],
 "id": 2
}

Можно использовать маски ? (один символ) и (любая последовательность).

2.3 Резервирование (reserv_numbers)

{
 "jsonrpc": "2.0",
 "method": "reserv_numbers",
 "params": [
 "<session-id>",
 "example-client",
 ["4951234567", "4952345678"],
 30 // таймаут в минутах (15‑7200)
 ],
 "id": 3
}

2.4 Бронирование (book_numbers)

{
 "jsonrpc": "2.0",
 "method": "book_numbers",
 "params": ["<session-id>", ["4951234567"]],
 "id": 4
}

Бронь действует 31 день, автоматически продлевается при повторном вызове.

2.5 Продажа (sell_numbers)

{
 "jsonrpc": "2.0",
 "method": "sell_numbers",
 "params": ["<session-id>", ["4951234567"]],
 "id": 5
}

2.6 Отруливание (install_numbers)

{
 "jsonrpc": "2.0",
 "method": "install_numbers",
 "params": [
 "<session-id>",
 ["4951234567"],
 "operator-42",
 "equipment-group-7",
 0 // grace = 0 – без промо‑периода
 ],
 "id": 6
}

2.7 Возврат в свободный пул (return_numbers)

{
 "jsonrpc": "2.0",
 "method": "return_numbers",
 "params": ["<session-id>", ["4951234567"]],
 "id": 7
}

2.8 Перемещение в «отстойник» (buffer_numbers) и вывод (detach_numbers)

{
 "jsonrpc": "2.0",
 "method": "buffer_numbers",
 "params": ["<session-id>", ["4951234567"]],
 "id": 8
}

Как оформить запрос: пошаговое руководство

1. Получить доступ к API. Обратитесь в отдел Технической поддержки (см. контакты ниже) и запросите логин, пароль и набор прав.
2. Подключиться к сервису. Выполните запрос connect – получите session-id.
3. Сформировать критерии поиска. Определите нужный регион, тип номера (простой, серебряный, золотой и т.д.) и примените маски, если требуется.
4. Выполнить поиск. Метод search_numbers вернёт список подходящих номеров.
5. Резервировать выбранные номера. Укажите таймаут (рекомендовано 30 минут) – номер будет недоступен другим клиентам.
6. Бронировать (если клиент подтвердил покупку). Бронь гарантирует удержание номера до 31 дня.
7. Продать номер. После получения оплаты вызовите sell_numbers.
8. Отрулить на оборудование. Укажите operator-id и equipment-group-id. При необходимости задайте grace=1 для промо‑периода.
9. Контролировать статус. При необходимости вернуть номер в свободный пул используйте return_numbers или переместить в отстойник buffer_numbers.
10. Закрыть сессию. По окончании работы просто дождитесь истечения часа – сессия будет автоматически аннулирована;

Технические детали реализации

4.1 Протокол и формат

Все запросы отправляются методом POST в формате application/x-www-form-urlencoded с полем jsonrpc. Пример на PHP (фрагмент из официальной документации):

function rpc_did_api_send_request($params) {
 global $DIDAPIHost;
 $post = ['jsonrpc' => json_encode($params)];
 $ch = curl_init("$DIDAPIHost/");
 curl_setopt($ch, CURLOPT_POST, 1);
 curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
 $result = curl_exec($ch);
 if ($result === false) {
 throw new Exception(curl_error($ch));
 }
 curl_close($ch);
 $decoded = json_decode($result, true);
 return $decoded['result'];
}

4.2 Обработка ошибок

В случае ошибки сервер возвращает объект:

{
 "jsonrpc": "2.0",
 "error": {
 "code": -32602,
 "message": "Invalid params"
 },
 "id": 9
}

Коды ошибок соответствуют спецификации JSON‑RPC 2.0. Рекомендуется реализовать логирование всех ответов и повторять запросы при -32600 (Invalid Request) или сетевых сбоях.

4.3 Права доступа

Каждый метод требует отдельного доступа. Ниже таблица основных прав:

Управление статусами номера

Номера могут находиться в одном из следующих состояний (поле access_state):

• free (0) – доступен для резервирования.
• reserved (1) – временно удержан клиентом.
• booked (2) – забронирован (до 31 дня).
• sold (3) – продан, но ещё не отрулен.
• installed (4) – отрулен на оборудование.
• buffer (6) – находится в «отстойнике» (до 3 мес.).
• detached (7) – откреплён от оборудования.

Переключение между статусами происходит только через соответствующие методы, что гарантирует целостность данных и предотвращает «гонки» за один и тот же номер.

Часто задаваемые вопросы (FAQ)

6.1 Как быстро узнать, когда номер будет доступен?

Поле ready в ответе метода search_numbers показывает количество месяцев до момента подключения. 0 – сразу.

6.2 Можно ли изменить таймаут резервирования?

Да, параметр timeout принимает значения от 15 до 7200 минут. По умолчанию – 15 минут.

6.3 Что делать, если запрос возвращает Invalid Request?

Убедитесь, что JSON‑строка передаётся в поле jsonrpc формы, а не в теле как raw‑JSON. См. пример функции rpc_did_api_send_request выше.

6.4 Как получить список всех доступных тарифов?

Тарифы хранятся в отдельном справочнике, доступ к нему реализован методом get_tariffs (доступ view-tariffs). Обратитесь к технической поддержке за инструкцией.

Контакты для обращений

Запрос управления номером телефона через Numbering API позволяет полностью автоматизировать процесс работы с телефонными номерами: от поиска до установки на оборудование. При правильной настройке прав доступа и корректной обработке ответов вы получаете гибкую, масштабируемую систему, которую можно интегрировать в любой CRM‑или биллинговый сервис.

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