Перейти к основному содержимому

Обновление данных об операторах

Веб-сервис позволяет получать информацию о телефонных номерах и обслуживающих их операторах мобильной связи, включая данные о номерах, для которых был изменен оператор. Сервис основан на HTTP API.

подсказка

Клиент может использовать эти данные, чтобы создать и обновлять собственный экземпляр справочника номеров с целью минимизации затрат на SMS-рассылки.

Клиент отправляет POST-запрос, в теле которого содержится пакет provideOperatorRequest в формате XML или JSON с номером версии обновления данных MNP. Платформа обрабатывает запрос клиента и отправляет ответный пакет provideOperatorResponse, содержащий структурированную информацию об операторах и телефонных номерах.

к сведению

URL-адрес подключения сообщается клиенту после заключения договора на использование сервиса

warning

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

Выбор формата передачи данных​

Формат передачи данных определяется заголовком HTTP-запроса Content-Type. Допустимые значения: application/xml или application/json.

к сведению

Если в запросе не указано значение заголовка Content-Type, заголовок имеет значение application/xml или заголовок имеет значение отличное от application/json — сервер будет ожидать запрос в формате XML. Ответ будет также возвращён в формате XML.

Пакет provideOperatorRequest​

В секции payload POST-запроса provideOperatorRequest передается обязательный параметр fromVersion – номер версии обновления, начиная с которой требуются данные MNP.

warning

В ответном пакете выводятся данные не более чем 10000 обновлений, начиная с указанной в запросе версии.

Примеры пакета​

<!-- XML -->
<provideOperatorRequest>
<header>
<auth>
<login>test</login>
<password>test</password>
</auth>
</header>
<payload>
<fromVersion>123</fromVersion>
</payload>
</provideOperatorRequest>
//JSON
{
"provideOperatorRequest": {
"header": {
"auth": {
"login": "test",
"password": "test"
}
},
"payload": {
"fromVersion": "123"
}
}
}

Пакет provideOperatorResponse​

В случае успешной обработки запроса платформа возвращает пакет provideOperatorResponse с результатами в секции payload: статусом выполнения запроса, данными об операторах и телефонных номерах. При некорректном синтаксисе запроса или недоступности сервиса возвращается пакет errorResponse с кодом error-syntax или error-system.

Параметры пакета​

ПараметрТипХарактерОписание
payload/codeStringОбязательныйСтатус выполнения запроса. Возможные значения:
- ok – запрос выполнен;
- error-auth – ошибка авторизации;
- error-forbidden– недостаточно прав для вызова метода;
- error-from-version-format– некорректный формат параметра fromVersion.
payload/countryListObjectОбязательныйСписок стран.
.../countryList/countryObjectОбязательныйСтруктура с информацией о стране оператора.
.../country/codeStringОбязательныйКодовое обозначение страны в БД.
.../country/nameStringНеобязательныйНазвание страны.
.../country/descriptionStringНеобязательныйОписание страны.
.../country/operatorListObjectОбязательныйСтруктура с данными операторов связи.
.../operatorList/operatorObjectОбязательныйСтруктура с данными оператора связи.
.../operator/codeStringОбязательныйКод оператора в БД.
.../operator/nameStringНеобязательныйНазвание оператора.
.../operator/descriptionStringНеобязательныйДополнительная информация об операторе.
.../operator/standardStringНеобязательныйСтандарт мобильной связи. Пример: gsm.
.../operator/unitListObjectОбязательныйСписок территориальных подразделений оператора.
.../unitList/unitObjectОбязательныйСтруктура с данными территориального подразделения оператора.
.../unit/codeStringОбязательныйКодовое обозначение подразделения в БД.
.../unit/nameStringНеобязательныйНазвание подразделения (юридического лица). Пример: ОАО "Мобильные ТелеСистемы".
.../unit/descriptionStringНеобязательныйДополнительная информация о подразделении.
.../unit/regionListObjectОбязательныйСписок регионов.
.../regionList/regionObjectОбязательныйСтруктура с данными региона, к которому относится номер абонента.
.../region/codeStringОбязательныйКодовое обозначение региона в БД.
.../region/nameStringНеобязательныйНазвание региона. Пример: Саратовская область.
.../region/descriptionStringНеобязательныйДополнительная информация о регионе.
.../region/timeZoneStringОбязательныйЧасовой пояс региона. Пример: Europe/Samara.
.../region/prefixListObjectОбязательныйСписок телефонных номеров, переведенных в территориальное подразделение оператора.
.../prefixList/prefixObjectОбязательныйДанные телефонного номера.
.../prefix/codeIntОбязательныйУникальный код префикса.
.../prefix/nameStringОбязательныйНазвание префикса. Обычно совпадает с кодом.
.../prefix/descriptionStringНеобязательныйДополнительная информация о префиксе.
.../prefix/addressPrefixStringОбязательныйЗначение префикса– начальная часть или полный телефонный номер. Все номера, начинающиеся с этого префикса, относятся к одному оператору и региону. Примеры префиксов: 7981860, 79261234567.
.../prefix/mnpBooleanОбязательныйЕсли true, то в ответе платформы возвращен полный номер, для которого был изменен оператор. Если false, то возвращена начальная часть, с которой начинаются несколько номеров.
.../prefix/removeBooleanОбязательныйЕсли false, то значение префикса актуально. Если true, то префикс устарел и его не следует учитывать.
.../prefix/versionIntОбязательныйВерсия обновления.

Примеры пакета​

<!-- XML -->
<provideOperatorResponse>
<header/>
<payload>
<code>ok</code>
<countryList>
<country>
<code>ru</code>
<name>Россия</name>
<description>Россия</description>
<operatorList>
<operator>
<code>ru-megafon</code>
<name>МегаФон</name>
<description>МегаФон</description>
<standard>gsm</standard>
<unitList>
<unit>
<code>ru-megafon-megafon_ural</code>
<name>ОАО "Мегафон" Уральский филиал</name>
<description>ОАО "Мегафон" Уральский филиал</description>
<regionList>
<region>
<code>ru-megafon-megafon_ural-sverdlovskaya_oblast</code>
<name>Свердловская область</name>
<description>Свердловская область</description>
<timeZone>Asia/Yekaterinburg</timeZone>
<prefixList>
<prefix>
<code>79122369285</code>
<name>79122369285</name>
<description>mnp</description>
<addressPrefix>79122369285</addressPrefix>
<mnp>true</mnp>
<remove>false</remove>
<version>80419</version>
</prefix>
<prefix>
<code>79122370644</code>
<name>79122370644</name>
<description>mnp</description>
<addressPrefix>79122370644</addressPrefix>
<mnp>true</mnp>
<remove>false</remove>
<version>80421</version>
</prefix>
</prefixList>
</region>
</regionList>
</unit>
</unitList>
</operator>
</operatorList>
</country>
</countryList>
</payload>
</provideOperatorResponse>
// JSON
{
"provideOperatorResponse": {
"header": {},
"payload": {
"code": "ok",
"countryList": [
{
"code": "ru",
"name": "Россия",
"description": "Россия",
"operatorList": [
{
"code": "ru-mts",
"name": "МТС",
"description": "МТС",
"standard": "gsm",
"unitList": [
{
"code": "ru-mts-mts",
"name": "ОАО \"Мобильные ТелеСистемы\"",
"description": "ОАО \"Мобильные ТелеСистемы\"",
"regionList": [
{
"code": "ru-mts-mts-omskaya_oblast",
"name": "Омская область",
"description": "Омская область",
"timeZone": "Asia/Novosibirsk",
"prefixList": [
{
"code": "79502193645",
"addressPrefix": "79502193645",
"name": "79502193645",
"description": "mnp",
"mnp": true,
"remove": false,
"version": 86250
},
{
"code": "79095355525",
"addressPrefix": "79095355525",
"name": "79095355525",
"description": "mnp",
"mnp": true,
"remove": false,
"version": 90791
},
"..."
]
}
]
}
]
}
]
}
]
}
}
}

Ответ в случае некорректного формата запроса.​

Если провайдер не может обработать запрос, он отправляет в ответ пакет errorResponse с кодом ошибки.

File IconОтвет на ошибочный пакет
<!-- XML -->
<errorResponse>
<header/>
<payload>
<code>error-syntax</code>
</payload>
</errorResponse>
// JSON
{
"errorResponse": {
"header": {},
"payload": {
"code": "error-system"
}
}
}